Don't repeat yourself: Effective information management in the system development process

References to non-existent chapters or documents, outdated figures, inconsistent terms!

Unmaintained system architecture documentation often raises more questions than it is able to answer. Accordingly, care should be taken to ensure that all information is kept up to date.

However, even with the best intentions, precisely defined workflows, and strictly adhered-to development processes, mistakes will creep in every now and then. As a result, the information is not always completely trustworthy and must be checked more often during implementation.

The following section highlights the issue of information management in the system development process. The weaknesses of the “classic” document-centric approach are addressed and alternative approaches are highlighted.

Why is it so difficult to keep the information up to date?

A system architecture has a hierarchical structure, which is usually described in one or more documents by means of figures and text.

Figure 1 shows an example of the structure of a system architecture. On one hand, the arrows represent the hierarchical dependency, and on the other, the flow of information (terms, etc.) throughout the course of the design process.

Thus, the information is spread over several documents and images, and if one piece of information is used in several places, it is always a duplicate. This means that each time a copy of the information is made, there is no longer any connection to the original information.

The issue here is evident. To make a change correctly, the information must be adjusted in all places where it is used. This is not only very time-consuming but also prone to error, as it is not known where else the corresponding information is being used.

The continuous copying and passing on of information are strongly reminiscent of the well-known children’s game “Chinese Whispers”, the appeal of which lies in the fact that mistakes are inevitable.

In Figure 2, this simple game is used as an example to show what could happen with a parameter designation—in this case even without introducing a content error. However, this is also very detrimental to the comprehensibility of a system architecture.

How can information divergence be prevented?

If we look at the “Chinese Whispers” example, the solution is probably obvious.

And just like that, all the fun of the game is ruined. However, for all other cases where divergent information is no fun, this is very advantageous.

In software development, there is a basic principle that aims to do just that: “Don’t repeat yourself”. The main goal is to avoid redundancy in order to increase consistency. This principle can also be applied to a system architecture. This would make it possible to keep them up to date easily and with little risk of error, benefiting not only the design process but also the development and lifecycle process.

Another way to achieve this is by continuously synchronizing information. In this case, any changes made to information are automatically propagated to all instances where it appears. This is a decentralized approach in which a software development analogy most closely resembles a Git repository, with the ability to merge multiple information assets.

How can this be implemented?

Single Point of Definition

“The code is the design” is another approach to software development that can be seen as either pragmatic or radical. Perhaps this approach is also a result of the “Law of the Instrument” (“If your only tool is a hammer, every problem looks like a nail”).

And while the simplicity of this idea has a certain appeal, it comes with too many limitations.

• Limitation to software-only projects.
• Comprehensibility suffers enormously from being overloaded with too many unnecessary details.
• The purely text-based medium does not allow for any explanatory graphic elements.

A somewhat more general approach is to use a central information manager, which manages information centrally and makes it available for the various areas of application. This idea is nothing new and is used in software development—for example in the “Model View Controller” concept. In systems development, this is often referred to as “model-based…” or “model-driven…”. The term “model” refers to the place where the central data is stored or managed.

In Figure 4, the example of the structure of a system architecture is shown above, with a central information management instance added.

However, this approach needs stronger support from specific software solutions, since information must be obtained from the “system model”. As a result, the architecture documents are no longer the direct output of the design process but must be generated from the “system model” in a separate step.

Although this involves changing the usual working tools to a certain degree, the advantages of such a solution outweigh the disadvantages. This can be seen not least from the fact that similar concepts have already been established in other areas. Examples include CAD software for mechanical development or ECAD software for electronics development. In IMT, for example, “SOLIDWORKS 3D CAD” and “Altium Designer” are used for this purpose.

Synchronisation

A common name for this approach is “roundtrip engineering”, where information in different documents, software artifacts, etc. is to be kept in sync.  It describes something like the ideal image of a software architecture, or even the implementation of a whole product. Regardless of where the information is edited, it is automatically tracked in all places where it is used. It promises even more: Regardless of whether a new component is added to the architecture or implementation, you get the same complete set of documents, software artifacts, etc. As nice as this would be, it’s not all plain sailing from here.

The fundamental problem is that this assumes a one-to-one relationship between all hierarchical levels. This would not only lead to very strict limitations in terms of implementation, but in some cases, it is not even achievable, as abstraction at higher levels means that not all the information is available.

That being said, if we look at this more pragmatically, it becomes apparent that this is not even necessary for the case of application of system development. If it is clearly defined at each level which information is defined, it actually seems to be much more understandable. With the exception of this limitation, centralized data storage, which was introduced earlier, can provide the same functionality.

Can central information be used outside of the system architecture?

Of course, it would be consistent to use this central data in as many aspects of system development as possible. However, this would require all the necessary functions to be integrated into a software solution, or at least a defined interface to share the information. However, since the different areas of system development, each has very specific requirements and there are already very good stand-alone software solutions for this (e.g. “SOLIDWORKS 3D CAD” and “Altium Designer”), it would probably involve an enormous amount of effort to also use the information directly in the specific CAD applications.

However, for the most agile part of system development—software development—it is quite possible to use code generation to create the structure and so-called “boilerplate code” for implementation. This allows the benefits of centralized information management to be leveraged right through to implementation. For this purpose, IMT relies on its own in-house developed software tool “DATAFLOW Designer”, which supports not only the provision of boilerplate code but also verifies conformity to standards.

The goal is an up-to-date, consistent, and comprehensible system architecture that provides every developer with the required information quickly and easily. To achieve this, the developers should be supported in the best possible way during creation and customization. Central information management is a fundamental building block for this, which makes it possible to support developers in a variety of ways—from design to implementation. The achievable increases in efficiency and quality benefit both the customer and the developer.