System Documentation
Let's talk in more detail about documentation. You already know that system documentation is a description of a system on some kind of physical medium. This could be a parts catalog, a product brochure, a computer-based model of the system, or text on paper. The words suggest[1] the following: here, objects from the physical world are being listed—brochure, computer model, paper. However, when we talk about media, we haven't said anything about the content of the description. The content can be seen, read, heard, and so on. It characterizes the system according to various parameters[2].
The concepts of "implementation," "description," and "documentation" are needed to avoid confusion when discussing a system. These concepts help direct attention and allow us to discuss each aspect separately, rather than lumping everything together[3]. Let's look at an example. A person, as a biological being, can be considered a system. This person is an object in the physical world and exists "in the flesh," meaning the "person" system is literally implemented in reality. It has numerous descriptions, such as height, weight, hair and skin color, and so on. There is also a description in the form of last name, first name, and middle name.
When we talk about descriptions, we understand that they do not exist in the physical world. When we refer to a person by name, we are mentioning a description of the person. This exists in the mental space. But there is also system documentation: a birth certificate, passport, international passport, driver's license, and so on. These documents contain a specific description of the "person" system. The documents exist in the physical world, and they contain a description[4], which is of interest to certain project roles. For example, a driver's license is of interest to a traffic inspector. If these interests did not exist, there would be no description, and there would be no need to create such documentation.
The same division into implementation, description, and documentation of the system can be made for inanimate objects. Let's take a milkshake as an example. On one hand, the drink itself in the physical world is the implementation of the system. At the same time, this milkshake has various descriptions: its name, recipe, and so on. There is also system documentation on paper, which lists the name and ingredients, and there is documentation in the form of a menu with a photo and the price of the drink.
Descriptions refer to certain characteristics or properties of a system. This information does not exist in the real world. For example, you cannot say that a person's age of "42 years" exists somewhere in the physical world and has its own length-width-height-time (4D dimension). You can point to a person, but that would be the implementation of the system. You can point to the number "42" in the physical world only if it is present on a specific information medium.
So, documentation can take the form of an IT model, a diagram, a table, text on paper, or in a computer. In other words, when we say "documentation," we are focusing on the information medium. This remains the priority in the discussion until the words "implementation" or "description" appear in the conversation.
Descriptions can be informal or formal. Most people do not realize the importance of formal descriptions and are satisfied with only informal ones. In complex projects, when we are dealing with numerous interests, formal descriptions are essential: they are created using a specific method and recorded on a medium. They help clarify the subject of interest, because as you begin to create descriptions, you gain a better understanding of the stakeholders. Informal descriptions often remain in people's minds and may not be based on any formal method of description. Much of what is simply thought up in one's head is forgotten.
As we mentioned earlier, formal descriptions of subjects of interest are created using specific description methods (practices). Each description method has a conceptual minimum and principles. This is covered in the "Rational Work" course. Systems thinking relies on knowledge of ontologics (ontology and logic), so in a system description, you need to be able to read and create different models of the system, as well as work with models that are understandable to a computer.
To create a successful system, certain role-based interests must be addressed. This is achieved by creating models that respond to the selected subjects of interest in the system. That is why it is so important for us to understand system descriptions. To implement a successful system in reality, you need to work with system descriptions. And these depend on the subjects of interest of the project roles.
Most of you work with numerous system descriptions. During the modeling session, try compiling a table that lists the documents you create or participate in creating, or documents made by your colleagues that you use in your work. Match each document to the system it describes. Also, think about which systems are described in your company's development strategy or in another similar document.
Although modern office workers deal with descriptions, it is important not to lose sight of the physical world. Always look for the implementation of the system. Systems thinking is, first and foremost, about the physical world, even though it deals with descriptions: "descriptions are nothing, but what they describe is everything!" All descriptions are made solely for the purpose of changing what is described in the physical world!
From now on, always pay attention to the words your conversation partner uses. For example, how often do they use words from the physical world or the mental space? Or what do they want to discuss right now: a substantive question, the form of presenting content, or something else? ↩︎
According to which parameters? According to those that are of interest to the many stakeholders. ↩︎
Our brains don't have enough processing power to discuss a system from several perspectives at once. In addition, these concepts may be of interest to different roles. ↩︎
A substantive characteristic of the system. ↩︎