System Description ​

System documentation/system description (system description) --- these are documents/artifacts/work products that implement the definition alpha of the system (system definition). If there is a system, it is usually described: it is implied that a system usage concept exists, its design/design exists (which includes the system concept, architecture as a set of architectural solutions, as well as engineering justifications, manufacturing details, description of the manufacturing method/technology, etc.). We may simply not know it yet, even though it is there - the system is in space-time, and the time may be in the future, while we are in the present, so we simply have not thought about these descriptions and have not documented them. Or we just have not yet found the performers who create such descriptions of project roles, and have not thought to ask them the right question yet - and they will provide us with the missing parts of the description, as they know them, it's just that we don't know them yet. In any case: if there is a system - there is a usage concept, there is a system concept, there is its architecture, possibly simply not yet identified/discovered (or already existing ones have not been found, or they have not been invented and documented yet): we already know the types of meta-meta-models, it is only left to obtain the objects themselves. It is not that "we do not know if they exist or not." They exist, here are their types - this means that attention to them is already present, it is brought up by the types already known to you! It is just necessary to identify them or even design them. When you go into a completely new project, you already know a lot about what you need to watch there, you are not in complete ignorance! You already know the meta-meta-model, and sometimes the meta-model as well (if you will be working in an applied subject area, the practice of which you have already mastered). Therefore, you already know something about the world, but something (a model, without any "meta") will have to be learned within the project itself, and also keep track of state changes.

To manifest the world the description of the system, it needs to be recorded on some medium, so that system documentation appears - to write down all these models (and sometimes texts, photos, which do not resemble models, nevertheless, they also reflect something important in the real system, describe something in it, so boldly consider them as models as well, except they are less formal descriptions) on paper, or represent them in electronic form as records in a database. If there is a system - then someone has singled it out from the surrounding world, thinks about it. Thinks - which means something is describing it, or describing it as a whole, "the system in the eyes of the beholder". If it cannot be described, it means the system has not yet been isolated from the surrounding world. We must clearly distinguish that the existing system description is always described as an alpha and the existing system documentation is not always a work product/artifact/document.

Sometimes system definition is translated as "system definition". In this case, the term should not be confused with "dictionary definition," like "our system - it is this and that." No, it is a variety of information about the embodiment of the system, it includes a variety of models of the target system, and often it is a constructive description (in the sense of constructivism: "to describe an object, you need to specify the operations of its construction"), so the system creation is described and its operations - this will be the system description. So, the one phrase of "dictionary definition" will not replace it, this term has a completely different meaning of the term system definition.

The ISO 42010 standard provides recommendations on how to think about system description/system description. The standard only talks about architectural description, in the old understanding of architecture, but its provisions are quite applicable to any descriptions, i.e. usage concepts, system concepts, and architecture.

Here is the schema-setting thinking about system descriptions from this standard, modified using OMG Essence provisions:

In life with direct engineering, everything usually starts with the development (identification, invention, coordination among each other) and documentation of some role-based types of descriptions (parts of the usage concept, system concept, architectural solutions, and so on), and then from the descriptions, the project team moves on to the embodiment of the system in the physical world (manufactures/produces the system, puts it into operation) - all this in a continuous system development cycle. If this is reverse engineering, then everything is the other way around: we take a system in the physical world and restore all descriptions for an already finished system. Usually in projects, reverse engineering is done for the suprasystem, and direct engineering for the system of interest.

If you find yourself in an organization (client, contractor, or have just joined a project team), you are conducting reverse engineering of that organization: understanding what is happening with creation systems. If you need to organize a system creator - you perform direct engineering, prepare all those descriptions and present them to people (the course "Systems Management" is all about this).

In philosophical logic, it is recommended to always start with the embodiment of the system, even if this embodiment will exist only in the future: it is necessary to envision and describe a possible world in which the system embodiment exists! At no time should it be forgotten that an embodiment of the system is needed, and the description (given to us in the form of informational models, drawings, manufacturing instructions, and so on.) is only necessary because without a description, it is very difficult to embody a working system.

There is no specific reading direction (from left to right, or right to left, or bottom to top, or top to bottom) for objects of attention for system description in this diagram. Different project roles for different purposes read this diagram in different directions. But the main element of the diagram is, of course, the system embodiment. All the activity is aimed at it, and it always needs to be kept in mind (reminding that all such diagrams are checklists for objects that need to be kept in mind when thinking about systems).

The diagram starts with the familiar distinction between system realization and system definition.

For simplicity, most relationships in the diagram (except for one: satisfies/defined in one direction and characterizes/defined in the other direction) are given only one connection name, but this does not mean that there is no reverse relationship. This is a common property of all such diagrams: even the "part-whole" relationship in one direction is read as "includes" or "consists of", in the other direction it is read as "is part of" or "is included."

Each relationship between objects in this diagram can be read in two directions, for example, "system description is expressed by system documentation/system description," "system documentation documents system definition." Both "system documentation" and "system description" can be said as well as "system definition" and "description of the system."

Note that documentation does not fix but documents constantly changing descriptions throughout the project! Avoid using the word "fixes," as people usually think it means not documenting (as you think when you pronounce the word "fixes"), but rather declaring the description as no longer changing.

The fixation or fixing of requirements (much less often is said about fixing the usage concept, and that was one of the reasons for abandoning the development of requirements in favor of the usage concept) for most people means not recording requirements on paper or in a database but declaring the current set of requirements as stable and unchangeable! But in system thinking, you are better at describing the system more and more (or describing a better system, as you understand how it will be used, in what environment), thus changing the usage concept - documentation does not hinder this, system models are not "fixed" at any time during the project! You can administratively declare some version as stable. Engineers mention in this case a baseline, but it does not mean "fixation"! The changes of system descriptions will be collected and documented in other artifacts (a document of the "working version", not a document of the already approved "baseline"), and then the baseline will change through some administrative project change management procedure. But even then there are changes: trunk development

Here is the same schema in the English language:

System description (system definition) consists of role/aspect-specific/particular system descriptions (views), which are defined by the target characteristics (concerns, subjects of interest/preoccupations) and specified by aspect descriptions methods (viewpoints). Role/aspect-specific/particular system descriptions are precisely the usage concept (developed by the role of a design engineer), architecture (formulated by the role of an architect), and so on - descriptions made by various engineering roles, presented in the course "Systems Engineering." But in management, for example, it will not just be architecture, but org-architecture, and the organization's "usage concept" will be a business model, where the need for the organization is justified (and a businessman will be responsible for it). Aspect descriptions - this can be anything that describes the system in a convenient way for discussing role interests.

For clarification, here the word "particular" is used in the sense of "not full, not everything - one type of description for the entire system," not in the sense of "dedicated to part of the system, taken by the part-whole relationship." "Particular" does not mean "about a part of the system" here!

Of course, there may be multiple role/aspect-specific/particular descriptions. For example, a role may be interested in finances. Then the role description will be financial, the models will be there - the financial balance sheet, the income statement, the cash flow. How to make these descriptions? These descriptions can be made using the RAS (Russian Accounting Standards) or IFRS (International Financial Reporting Standards) description method, and the meta-models - these are formats of representing the balance sheet, income statement, cash flow in the respective role description methods (RAS or IFRS). If a financial specialist is interested in both description methods, then he will get two descriptions - and for RAS and for IFRS. How will these descriptions be documented? Either on paper, or in Excel tables, or in a computerized accounting program database - in any case, the content of the descriptions can be discussed without discussing the format of representation on information carriers.