Best practices for a system documentation

Software Documention

Although the Agile Manifesto places a higher value on functioning software than on comprehensive documentation, documentation is still important [1]. Because software documentation is a description that provides precise information about software systems [2] and supports software maintenance [3]. In addition, the purpose of such documentation is to enable software developers to communicate with each other. This should enable the future development of software efficiently [4].

Documentation is geared towards different target groups. The target groups include software developers, software maintainers, software users, and management. Since these target groups have different goals, documentation is divided into different types [3].

One of these variants is system documentation. System documentation contains all information that describes a system or software. The purpose of this documentation is to assist readers in understanding and maintaining the system. As with user documentation, it is important for system documentation to structure and convey the content to the reader with an overview. This allows the reader to navigate the system's various aspects and take in detailed information [3].

When it comes to large and complex systems, system documentation, according to Sommerville [3], should contain the following:

• A document that shows and justifies the requirement for the system.
• A document that describes the software or system architecture.
• A description of the architecture for each program in the system.
• A description for each component in the system that describes the functionalities.
• A system maintenance guide that describes the known problems of a system. It also indicates which hardware and software the system depends on and describes the development of the system or software.

Qualitative Attributes of a software documentation

The quality of documentation is mainly influenced by the quality of the structure, the formatting, and the content. The quality of the content is, in turn, determined by several qualitative properties [5].

Format

To optimally design documentation formatting, a few points should be observed. Many documentation users prefer graphical elements, as they greatly influence the understanding of the program. In addition, the writing style must also not be disregarded [6].

• Because the writing style of documentation has a great influence on the quality of the documentation. The writer should be able to use clear and concise sentences. It should be noted that this is not an easy activity. Texts have to be written, read, criticized, and rewritten until a certain level of quality is achieved [3]. Sommerville recommends the following practices [3]:
• Use active sentences instead of passive sentences.
• Long sentences that reveal several facts should be avoided. It is advisable to formulate several short sentences as it helps the reader to structure information.
• Paragraphs should contain a maximum of seven sentences since a reader can only store seven pieces of information with his or her short-term memory.
• Sentences should be formulated concisely. More emphasis should be placed on quality than quantity, as the understanding of the software is in the foreground.
• When a description is complex, the description can be repeated in a different way. Thus, the reader is offered several descriptions in order to understand a complex topic.
• It is recommended to use headings and sub-headings to structure information. It is important that the headings are numbered consistently and are listed in a table of contents.
• Facts should be presented in a list instead of a long sentence. Underlining the facts or using italics to create contrast is advisable.
• If the documentation refers to other chapters, the reader should be reminded of the chapter. This means that not only a reference number should be given but also a text that describes the chapter. Example: "In chapter 1.4, in which the relations of the tables are explained, ...".

• Another tool that can have a supporting effect are UML diagrams. The Unified Modeling Language (UML) is a group of graphic notations that is supported by a single metamodel. These diagrams help to design and build software systems [7]. For program designers, software architects, and developers, UML diagrams are important tools for building well-developed and useful software. In addition, the UML diagrams, which support the design and development process, can offer value for the technical documentation. They help the user of documentation to organize, visualize and understand complex programming concepts [8]. Developers do reverse engineering and sketch UML diagrams from existing code in order to understand it afterward. These are then used in documentation [7].
• Another methodology that improves the format is implementing code snippets with highlighted syntax. These provide the user of documentation with perceptual information and thus improve the legibility of the code [9]. Accordingly, the understanding of the software improves [10]. However, it is important to mention that this effect diminishes the more experience the user has in programming [11].

Structure

In addition, the structure of the documentation is also very important. The structure of documentation means how the content is organized in the documentation. Thus, we speak of content that is divided into chapters, sections, and subsections. The structure of documentation also greatly influences readability and usability. With well-structured documentation, readers are better able to extract information from it [3]. One possible standard that could be used here would be ISO / IEC / IEEE 26511: 2018 [12].

Content

In addition to formatting and structure, it is also important that the content is qualitative. To design the content qualitatively, the content must have certain qualitative properties:

• The information must be easily accessible. Information should be easy to find and not hidden. This also includes making the documentation generally accessible to users [5].
• It should also be ensured that the information is precisely described. The information described in Libra can make it difficult for users of the documentation to extract information [2, 13, 14].
• One characteristic that also influences the quality of the content is the mentioning of authors and contributors to the documentation. Changes to the documentation should also be recorded [15].
• Another important point is that the documentation is up-to-date. In parallel with the further development of software, the documentation must also be further developed. Disregarding this leads to the documentation having outdated information or not providing new information. As a result, users of the documentation are misled (Zhi, et al., 2014). Up-to-date documentation also supports the qualitative property that documentation is complete with regard to its information [16, 17].
• In addition, spelling and grammar are very important. An overall inadequate spelling and grammar mean that the user has problems working out the information because he has difficulties understanding the documentation [3]. In addition to spelling, it is also important that the information in the documentation is correct regarding the content. Because incorrect information leads to incorrect understanding

References

• [1] K. Beck, M. Beedle, A. van Bennekum, A. Cockburn, W. Cunningham, M. Fowler, J. Grenning, J. Highsmith, A. Hunt, R. Jeffries, J. Kern, B. Marick, R. C. Martin, S. Mellor, K. Schwaber, J. Sutherland and D. Thomas, “Manifesto for Agile Software Development,” 2001. [Online]. Available: http://agilemanifesto.org/.
• [2] D. L. Parnas, “Precise Documentation: The Key to Better Software,” in The Future of Software Engineering, Springer, Berlin, Heidelberg, 2011, pp. 125-148.
• [3] I. Sommerville, “Software Documentation,” Lancaster, UK, 2001.
• [4] A. Forward, “Software Documentation – Building and Maintaining Artefacts of Communication,” 2002. [Online]. Available: https://ruor.uottawa.ca/handle/10393/6148.
• [5] J. Zhi, V. Garousi, B. Sun, G. Garousi, S. Shahnewaz and G. Ruhe, “Cost, Benefits and Quality of Software Development Documentation: A Systematic Mapping,” 22 Oktober 2014. [Online]. Available: https://www.researchgate.net/publication/267215582_Cost_Benefits_and_Quality_of_Software_Development_Documentation_A_Systematic_Mapping.
• [6] S. Tilley and S. Huang, “A qualitative assessment of the efficacy of UML diagrams as a form of,” in SIGDOC '03: Proceedings of the 21st annual international conference on Documentation, 2003.
• [7] M. Fowler, UML Distilled: A Brief Guide to the Standard Object Modeling Language, Pearson Education, Inc., 2004.
• [8] N. MacKinnon and S. Murphy, “Designing UML Diagrams for Technical Documentation,” in Proceedings of the 21st annual international conference on Documentation, San Francisco, CA, USA, 2003.
• [9] T. Hendrix, Dean, Cross, J. H., Barowski, L. A., Mathias and K. S., “Providing Enhanced Visual Support for Software Development and Maintenance,” in Proceedings of the 36th Annual Southeast Regional Conference, New York, NY, USA, 1998.
• [10] D. J. Gilmore and T. R. G. Green, “Programming plans and programming,” Quarterly Journal of Experimental Psychology, Section A, pp. 423-442, 1988.
• [11] A. Sarkar, “The impact of syntax colouring on program comprehension,” in Proceedings of the 26th Annual Conference of the Psychology of Programming Interest Group, Bournemouth, UK, 2015.
• [12] ISO/IEC JTC 1/SC 7 Software and systems engineering, “ISO - ISO/IEC/IEEE 26511:2018 - Systems and software engineering — Requirements for managers of information for users of systems, software, and services,” ISO, 12 2018. [Online]. Available: https://www.iso.org/standard/70879.html. [Accessed 24 05 2021].
• [13] D. L. Parnas and S. A. Vilkomir, “Precise Documentation of Critical Software,” in 10th IEEE High Assurance Systems Engineering Symposium (HASE'07), 2007, pp. 237-244.
• [14] D. L. Parnas, J. Madey and M. Iglewski, “Precise documentation of well-structured programs,” in IEEE Transactions on Software Engineering, 12 ed., vol. 20, IEEE, 1994, pp. 948-976.
• [15] R. Kylmakoski, “Efficient authoring of software documentation using RaPiD7,” in 25th International Conference on Software Engineering, 2003. Proceedings, 2003.
• [16] M. Kajko-Mattsson, “A Survey of Documentation Practice within Corrective Maintenance,” in Empirical Software Engineering, 2005, p. 31–55.
• [17] S. C. B. d. Souza, N. Anquetil and K. M. d. Oliveira, “A study of the documentation essential to software maintenance,” in Proceedings of the 23rd Annual International Conference on Design of, Coventry, 2005, p. 68‐75.
• [18] D. Schreck, V. Dallmeier and T. Zimmermann, “How documentation evolves over time,” in Proceedings of the 9th International Workshop on Principles of Software Evolution: in conjunction with, Dubrovnik, Croatia, 2007.
• [19] F. Lehner, “Quality control in software documentation based on measurement of text comprehension and text comprehensibility,” Information Processing & Management, p. 551‐568, 1993.