By Terence Pyle
Software design documentation plays a significant role in a software development environment and can be broadly defined to include any written or illustrated communication that describes how software works, what it does, and how to use it. In this article, I focus on software design documentation for software developers, sometimes called internal documentation. Common examples of software design documentation include requirements specifications, architectural documents, and detailed design documents.
These documents are read by individuals involved in the production of software, including managers, project leaders, and developers. Effective design documentation supports software development activities, keeps software quality high, and enables projects to be more easily transferred from one group to another.
Companies developing software either employ their own technical writers or outsource the creation of the documentation. This depends on the complexity of the software being developed and its demands on the documentation. Complex products with long-term development, which require detailed design documentation, benefit from having technical writers employed full-time. This way, the documentation can be created more quickly and precisely with the collaboration of subject matter experts. When subject matter experts do not write the documentation themselves, it’s because they are too submerged in their field of expertise. They might not see the subject matter from a broader perspective and thus may not write the information in the best way to suit their audience.
To write effective software design documentation, technical writers must understand why software developers seek information in their day-to-day tasks. In this article, I will first look at findings from studies that provide insight on what design information is most useful to them in their development tasks. Software developers need architectural understanding of the system software, including functional components and how those components interact, as well as detailed design information.
I will then present findings from studies that have investigated software documentation problems, identifying issues related to what information is included in design documents and how the information is written and organized. Finally, I’ll suggest some guidelines for creating successful design documentation that’s easier for software developers to read, understand, and use.
Software Development Methodology
In software engineering, you often hear the phase “software development methodology.” A software development methodology is a framework used to structure, plan, and control the process of developing system software.
The two most well-known methodologies are as follows:
- Waterfall, which might be more properly called the “traditional” approach
- Agile, a specific type of rapid application development and more recently developed than Waterfall
The principle of the traditional methodologies is that the development process is sequential and divided into phases. Only after one phase is finished can the work on the next phase begin. These methodologies suppose that if a project is analyzed and well planned at the beginning, it will be better implemented. One of the best-known traditional development methodologies is the Waterfall process. Figure 1 illustrates the sequential scheme of Waterfall.
Waterfall methodology is suitable mainly for projects with these criteria:
- Requirements are clearly defined and unlikely to change during the development cycle.
- New requirements are unlikely to arise.
- Resources include enough time and people to complete each phase of the cycle.
In a traditional Waterfall approach to software development, documentation is created mainly at the beginning and end of the project. At the beginning, requirements specifications documents describe the project to be developed, including its features, attributes, and behavior. Architecture and design documents define visual and construction principles to be used in the product.
Agile is an iterative, team-based approach to development. This approach emphasizes the rapid delivery of an application in complete functional components. As Figure 2 shows, agile methodology is characterized by continuous planning, development, testing, and integration, underpinned by collaboration within a self-organizing, cross-functional team. The team iterates quickly and flexibly to deliver customer value on demand.
The opposite of creating documentation at the beginning and end of the project, agile promotes creating documentation throughout the project. If you’re releasing functionality for each iteration, or every few iterations, comprehensive documents help users cope with the quick changes. Even if you don’t release frequently, it still pays to have the writer keep up with development so you don’t have to wait weeks at the end of development for your writer to document the product from scratch.
The Technical Writer’s Role on the Software Development Team
In agile development, documentation is included in the work done during each iteration. Therefore, agile methods advise that technical writers become members of the team and work physically in the same office or geographic location with the team. Such practice encourages communication between the developers, QA engineers, and technical writers. It also enables the technical writers to participate in meetings and thus be more involved in the creation of the product, which can be beneficial for all roles and the product itself. The technical writers advocate for the system’s users and can provide valuable feedback on the developed functionality while gaining technically accurate knowledge about the functionality directly from the other members of the agile team.
In software development, technical writers experiment with the documented software and interview the developers and testers about the software’s functionality. Especially important are technical writers’ soft skills, which are fundamental for keeping good relationships with subject matter experts, gaining information easily, working in teams, planning, and organizing working time effectively.
Software Developers’ Need for Information
Comprehending computer programs is a core software engineering activity. Software comprehension is required when a programmer maintains, reuses, migrates, reengineers, or enhances software systems. A large percentage of the software developer’s maintenance activities is spent studying the software to understand it and to determine how planned modifications might be implemented.
Software maintenance is a predominant activity in software development. Software development is a dynamic activity during which constant changes need to be incorporated into existing products, necessary to keep software systems up-to-date and useful. A major problem affecting software maintenance is the lack of up-to-date documentation.
Studies that have analyzed software developers’ day-to-day information needs have found the following: software developers have design questions—for example, developers need to know the intent behind legacy software architecture and current implementation. Design documentation communicates between members of the development team. When other developers are not available to answer questions, the design document provides big-picture information about the software system.
In a 2003 study, participants were asked what information developers needed to best support their development tasks. Responses indicated that the following aspects were most important:
- An overall understanding of the complete system
- Detailed information about components in their scope, together with interfaces, and in relationship to other components
Developers refer to the software documentation for the following tasks:
- Learning and working with a new software system
- Testing a software system
- Solving problems when other developers are unavailable to answer questions
- Looking for big-picture information about a software system
- Maintaining a software system
- Answering questions about a system for management or customers
- Looking for in-depth information about a software system
- Working with an established software system
Problems Affecting Software Design Documentation
Studies investigating software documentation problems have identified issues related to the information contained in design documents and how it’s written and organized, according to work by Emad Aghajani and colleagues. Here are some suggestions for ensuring that your design documents are accurate, complete, and up-to-date:
- Write only information that you understand, and then verify it
- Keep up with technical changes
- Strive to maintain consistency across all information about a subject
- Use tools that automate accuracy checks, and check the accuracy of references to related information
Documentation is incomplete if it does not contain the information about the system that the developers need to perform their tasks. Guidelines for making sure documentation is complete include the following:
- Cover all topics that support the developer’s tasks—and only those topics
- Cover each topic in just as much detail as the developers need
- Repeat information only when developers will benefit from it
A document is outdated when it does not reflect what’s implemented in the software code. Being up-to-date differs from correctness and completeness in that the information was likely correct and complete before a change was introduced.
Documentation issues related to how the content is written and organized include the following:
- Usability, or the degree to which readers can use the documentation to achieve their objectives effectively, including issues related to findability, organization, poor or inconsistent formatting, and accessibility
- Maintainability, or how easy it is to apply changes to the document’s content or make corrections to it
- Readability, or the extent to which documentation is easy to read, including issues related to clarity and whether the information is overly abstract or technical
- Usefulness, or its practical use to readers—for example, whether software developers can successfully achieve their goals using the document
Adding Value to Design Documentation
Studies of how software developers use documentation suggest that, to achieve greater documentation relevance, we must find ways to express the most useful information in less space and make the documentation easier to update (see, for example, Sergio Cozzetti’s 2005 SIGDOC paper). Results from such studies indicate that software engineers create and use simple yet effective documentation and ignore complex and time-consuming documentation. Software design documentation must be up-to-date and consistent to better serve the developers’ needs for information.
Using a documentation standard enables developing information with a consistent accepted reference for the format and content. This results in documents with a consistent appearance, structure, and quality and makes documents easier to read, understand, and use. (For information about ISO software documentation standards, check out Annette Reilly’s tcworld article.)
Conclusion
Technical writers are a vital part of the software development team and have just as much to do with product creation as developers, QA engineers, and designers. In fact, we need to be in constant communication with other departments to do our jobs efficiently. If we’re involved in the planning, we can identify where additional documentation might be needed. To create proper documentation, we must coordinate with the development and testing teams.
When colocated with the software development team, we can add value to the software design documentation with an understanding of what design information is useful to developers. When we identify software design documentation problems and issues related to how the information is written and organized, we can create documentation that is useful to our readers.
Terence Pyle (pyleterence@gmail.com) is a senior technical writer at Think Surgical, where he collaborates with a group of software engineers to write and edit software requirements and design specifications. He has worked in the field of technical communication for more than 30 years, providing technical writing and editing services to manufacturers and system integrators of electronic systems. He earned his MS in technical communication from Colorado State University. In his spare time, he enjoys researching his family history and meeting relatives at family reunions. He is a native Californian who has also lived in Colorado, Utah, and Wisconsin.
References
Aghajani, Emad, Csaba Nagy, Olga Lucero Vega-Marquez, Mario Linares-Vasquez, Laura Moreno, Gabriele Bavota, and Michele Lanza. 2019. “Software Documentation Issues Unveiled.” Proceedings of the IEEE/ACM 41st International Conference on Software Engineering (ICSE), 1199–1210.
Cozzetti, Sergio, Nicolas Anquetil, and Kathia M. de Oliveira. 2005. “A Study of the Documentation Essential to Software Maintenance.” Proceedings of the 23rd Annual International Conference on Design of Communication (SIGDOC 05), 68–75.
Kipyegen, Noela Jemutai, and William P. K. Korir. 2013. “Importance of Software Documentation.” International Journal of Computer Science Issues 10 (5) no. 1: 223–228.
Ko, Andrew J., Robert DeLine, and Gina Venolia. 2007. “Information Needs in Collocated Software Development Teams.” Proceedings of the 29th International Conference on Software Engineering (ICSE 07), 344–353.
Lethbridge, Timothy C., Janice Singer, and Andrew Forward. 2003. “How Software Engineers Use Documentation: The State of the Practice.” IEEE Software 20 (6): 35–39.
Project-Management.com. 2019. “10 Key Principles of Agile Software Development.” 21 September 2019. https://project-management.com/10-key-principles-of-agile-software-development.
Reilly, Annette D. 2016. “Standards for Software Documentation.” tcworld, April 2016. https://www.tcworld.info/e-magazine/translation-and-localization/standards-for-software-documentation-695.
Rost, Dominik, Matthias Naab, Crescencio Lima, and Christina von Flach Garcia Chavez. 2013. “Software Architecture Documentation for Developers: A Survey.” In European Conference on Software Architecture, edited by Khalil Drira, 72–88. Springer-Verlag Berlin Heidelberg.
Sarycheva, Yana. 2019. “Waterfall Model in SDLC.” 22 May 2019. https://xbsoftware.com/blog/software-development-life-cycle-waterfall-model.
