In the previous chapter, you learned what architecture documentation is and what it’s used for, with a few examples.
In this chapter, you will see how to correctly identify the project stakeholders' needs to create the right documentation.
Who Are the Stakeholders?
However, only a few of these groups will read your documentation. So let’s call them your target audience.
Write for Your Target Audience
It’s now time to ask who is going to read your documentation? Who are you writing the documents for?
At least for the following groups:
Developers
Database administrators
Software engineers
Software architects
The following table describes what these stakeholder groups need and what style and content you should use:
Target audience | Needs | Style to adopt | Content required |
Developers | General architecture of the solution, functional requirements, database structure, file structure. | Very technical. Use diagrams. | Structure of folders, files, and databases. |
Database administrators | General architecture of the solution, expected use of the system, identification of users. | Very technical. Use diagrams. | File structure, hierarchical description of files, relationships between files, index description. |
Software engineers or architects | General and detailed architecture of the solution, functional requirements, database structure, file structure. | Very technical. Use diagrams. Refer to a glossary of terms. | Description of the solution, main features of the system, short description of database and file structure. |
Example 1: Adapt Your Documentation
This is an example of hiring experienced software engineers such as in the table above. Imagine your company wants to develop a software system internally without recruiting developers for this project. It will, however, have to use an external service provider—the project requires the skills of experienced software engineers who specialize in secure storage and data transfer. The company doesn’t have these skills or experience internally.
These external data security specialists will need extremely detailed technical system documentation, which they’ll use to develop their solution. Therefore, you and your team need to draw up a specific document for them.
Another document? There’s already a lot of code here!
Example 2: The Database Administrators Are Also Stakeholders
This example involves communicating with the database administrators on your team as seen in the table above. Imagine you need to explain to the database administrators how your system works and how you want to develop it.
The basic design of the system database is a crucial stage as it is the foundation of your system—once created, it will support the whole structure and will be very difficult to change.
What information do database administrators need?
What are the main tables in the system? (Clients, products, system users, product components, general tables, etc.)
How do the tables interact with each other? (Can a client have several products? Do the product components depend on the products table?)
How can users search the tables? (By client ID, client name, product ID, etc.)
Reuse Parts of the Documentation
Software architects and developers are a lazy bunch! 🙂 The last thing they want to do is write the same document twice. You’ll find you can reuse diagrams and images in many different documents.
Here are a few examples of useful and reusable basic modules:
A general description of the solution.
Interfaces with other systems.
A description of the main features of the system from the user’s point of view.
A general description of database tables and indexes.
A general diagram of system security.
Let’s Recap!
A project stakeholder is a person, group, or entity that may influence (or be influenced) the project. Examples include project manager, project team, executive management, project client, line manager, subcontractor, consultant, or other company employees.
Write for your target audience: developers, database administrators, software engineers, software architects, etc.
Adapt your documentation: write specific documents for certain groups and stakeholders, where necessary. This will save time and avoid misunderstandings.
Reuse parts of your documentation—you’ll find you need to use the same diagrams and drawings in many different documents. Document certain basic modules and carefully identify them before writing the general documentation.
In the next chapter, we’ll look at some best practices for presenting your documentation with specific examples.
