Automated documentation of a critical industrial system

Types of documentation creation:

The semi-automatic documentation is carried out by the Sysparency software. The results are mathematical documentation of the functional logic, system-internal / external API documentation, class diagrams including inheritance. This process is carried out semi-automatically because the conversion into mathematical formulas and structured content requires manual checks and definitions. These results have both technical and functional relevance to the procedure and effort in the subsequent documentation. The manual creation of documentation includes classic methods of requirements engineering, such as the review of existing documents on the relevant topic, the preparation and consolidation of different types of results, such as: the preparation of technical workshops or iterative feedback loops with experts on the part of the client.   Sysparency organizes and controls the creation of the documentation independently in coordination with the internal, responsible employees from the development and specialist areas as well as the post-documentation project.  

Explanations of the semi-automated documentation

The semi-automated documentation is applied to those software parts in which the mathematical and technical core pieces of the software are coded. The Sysparency tool is used for the semi-automated creation of developer documentation. Sysparency analyzes the source code of the software to be documented, identifies information relevant to the documentation and transfers (transforms) this into high-quality documentation. The structure and content of the documents are essentially created in three steps. First, Sysparency identifies mathematical calculations in the source code and extracts them in the form of formulas, decision tables and, if necessary, function plots. Second, analyzes sysparency the comments in the source code, assigns them to the extracted formulas etc. using rule-based categorization and transfers the results to the resulting document. In the last step, information extracted using compiler program analyzes (e.g. control and data flow) is structured and the final structure of the generated documents is determined. A document generated in this way contains lists of the individual functionalities (based on the implementation) together with a brief description, checked preconditions, summarized process descriptions and mathematical functions of the individual functionalities. If necessary, the generated documents are manually post-processed and linked to other documents (e.g. API documentation). The functional view and information are collected in the course of workshops with the responsible know-how carriers and supplemented by sysparency. The preparation and follow-up as well as the moderation of these workshops are carried out by Sysparency experts. Following the workshops, the information is transferred to the documentation and incorporated in a structured manner.