Communicate the quality targets, context, and design drivers of your software architecture.
Developing software demands high levels communication between possibly quite large number of stakeholders. While direct communication typically is preferred, but not always practicable. Benjamin Kovitz lists the following principal benefits of documentation in Practical Software Requirements.
Documentation
- extends what the mind can grasp and remember
- gives the same story to each member of the team
- introduces new team members to the project
- protects intellectual equity
- helps the writer to better understand the problem
While the information about a software systems is unique, the basic structure of documents, especially to describe a software architecture, is not necessarily so. Teams communicating the structure and design principles may select a predefined structure, such as the arc42 Template, and smaller, much more confined templates for quality targets, views, and decisions. By selecting an existing structure authors and readers may save resources and are able to create value faster in a well-known environment.
For successfully communicating a software architecture it is important to drive the process of generating useful information from development artifacts automatically. This includes such classic living documentation artifacts as acceptance tests, but also static derived information as dependencies and system codes.
Types of Documentation
Besides communicating the system architecture, a software development project may need to document other aspects, too. Documentation is roughly organized in four types of documentation:
- Process documentation
- how do we want to work and what do we need to work? - Project documentation
- what have we actually decided, done, and must keep in mind? - System documentation
- the technical documentation for the team creating the product. - Product documentation
- relevant information for users of the product (including support teams).
Keep in mind that answering the "why" questions is essential for all kinds of documentation.
The projectdoc Toolbox provides tools for the four quadrants of documentation.
