System Documentation
Descriptions capture everything essential about a system—that is, everything that addresses the subjects of interest of the project roles that have been chosen to be addressed during the system’s creation. Creating a consistent description increases the likelihood of successfully implementing the system of interest in the physical world.
Systems modeling is carried out through thinking through writing, which involves special tools known as modelers. For example, such modelers can include pen and paper, Word, a wall with sticky notes and a marker, and more advanced modelers like Coda[1], CAD (computer-aided design)[2], and so on.
The work artifact of systems modeling using modelers is documentation. Documentation ultimately becomes the team’s external memory (exocortex)[3]. The format of documentation[4] can be text, outlines, tables, computer models, and so on.
Our course is also a modeler in the form of tables or high-level models, in which important systems thinking concepts are interconnected. By using the course as a simulator, you can practice mastering the necessary concepts for such high-level modeling (not entirely related to the subject area). High-level modeling includes designating[5] all important systems and subsystems, as well as their interrelationships. In addition, to understand high-level models, you will at minimum need to grasp the connection between the method of description and the subjects of interest, the difference between a “black box” and a “transparent box,” and broaden your understanding of the names and content of key documents in the main areas of interest[6].
Later on, you can use any spreadsheet editor (for example, Coda) to describe your project and the systems involved in it at a high level. However, for subject-specific modeling and for creating the corresponding documents for role-based interests, you will need to use applied theories and tools[7]. For example, CAD, 1C, PDM (Product Data Management)[8], CRM (customer relationship management)[9], and many others.
Within our course, you will learn what types of documents exist, which subjects of interest they address, how they are interconnected, and by which methods of description they are created. However, within the course[10], you will not study or create specific documents with models and descriptions. For example, we will discuss documents that describe the target audience or project roles, and we will also discuss the usage concept and architecture, but to develop specific instances of these documents, you will need to study the corresponding applied practices (methods of description).
Usually, in a project or enterprise team, there are specialists in applied methods (marketers, architects, product owners, etc.) who specialize in developing certain documents describing various subjects of interest. The goal of our course is to understand that all these documents can be viewed in the same way[11], and to see their interrelationships. To do this, you first need to master the systems language—that is, to know the relevant concepts of systems modeling.
For high-level modeling, where all important systems and subsystems, as well as their interrelationships, are described. ↩︎
For more detailed (subject-specific, applied) design, including the creation of design and technological documentation. ↩︎
On one hand, the modeler itself is also an exocortex, but the result of modeling is also considered an exocortex. This is an analogy with the brain, which engages in thinking, and then produces a result that is also stored in the brain. But we will consider documentation not as a biological brain, but as paper or computer models that can be accessed not only by their creator. ↩︎
The content of documentation consists of descriptions, which are determined by the subjects of interest of the project roles regarding the system. ↩︎
The name and a brief description (for example, its function, structure, etc.). ↩︎
For example, you need to know what documents like the “usage concept” and “system concept” are, and how they differ from a “balance sheet” or a “target audience description.” ↩︎
These need to be studied separately. For example, to prepare a balance sheet document (as a response to the subject of interest—taxes), you will need to study accounting theory and master a tool (for example, 1C). ↩︎
A product data management system or product versioning system. ↩︎
CRM contains databases describing the client base as a whole system in the physical world, and parts of the client base are individual clients. ↩︎
And even within the systems thinking course. ↩︎
For example, to see the roles that create them and to understand which methods are used. Or to pay attention to the project roles to whom the created documentation will be addressed. ↩︎