Before getting into the practical aspects of documenting a system, there are a couple of things you need to know:
The purpose of documentation.
At what point to create documentation for stakeholders.
The Purpose of Documentation
Imagine you’re building a house. Many different people will be working on it at different times—builders, electricians, roofers, carpenters, plumbers, etc. They all know how to do their work and what they must do, but they all require one essential thing: a building plan. While each of them will use it differently, they all need this document to build a house!
Use of Documentation
Your architecture documentation serves the same purpose for your software project. For example, you need to describe a system for many different people who speak different languages. Architecture documentation is used mainly for the following purposes:
As an internal contract between the project stakeholders, i.e., people, groups, or entities that may positively or negatively influence your project (or could be influenced by it). For example, these stakeholders could be your team, the project sponsors, external suppliers, the system users, or other company departments. A project should combine the work done by the different stakeholders through an agreement to ensure it meets expectations. This implicit agreement between the different parties within the company constitutes an internal contract.
As a communication tool that aids understanding of the heart of a system. A communication tool within a project aims to help two or more users reach a common goal by working together. The heart of a system refers to the characteristics that define what the system does, how it does it, and for whom, regardless of how it appears.
Documentation Helps Save Time and Ensure Consistency
If your documentation is incomplete or nonexistent, the parties working on it won’t understand the project in the same way, which will lead to an incorrect interpretation of the solution. Some may set out in the wrong direction and have to backtrack later. This wastes time and money and hurts team morale.
Likewise, you’ll have to describe the solution to each new team member or external provider repeatedly if you don't have comprehensive documentation. Therefore, documentation helps you save time and ensures consistency throughout the project.
When Should You Create Stakeholder Documentation?
You might be wondering when you should start documenting the architecture—before the start of the project, in the middle, or once you finish the project?
There are two phases of your software project during which you need to create documentation:
During the project proposal phase.
During the project implementation phase.
Project Proposal Phase
During the proposal phase, you present a software solution to the directors or managers of your company. They listen to your proposal and decide whether or not to invest their budget in the project.
Most companies generally seek these benefits: higher sales, greater efficiency, or more savings. However, the costs attached to a project are hiring staff, work hours, equipment purchased, and any special expenses.
What Should Be Done in This Phase?
At this stage, you only need general architecture documentation.
This document contains non-technical (or at least not highly technical) terms that all stakeholders can understand, including the project sponsors and other company executives. At this stage, your documentation is a tool for analysis, preliminary design, and cost estimation.
Real-life Example No. 1
Here’s a good example of a general software architecture document. It’s simple and easy to understand and comes from an actual project: implementing a new section for a special user group on a company website.
It’s a good idea to show this simple diagram to your company's board when you present your project proposal.
Project Implementation Phase
The second phase is the project implementation phase.
This implementation phase begins when your project is sold. Once the project is approved, you need documentation as a tool for maintaining quality and managing clients’ expectations.
Real-life Example No. 2
This is a technical diagram of the block diagram presented above for use in project implementation:
The aim here isn’t to scare you with complicated jargon, so let’s look at the terms in the above diagram:
Database driver: parts of the code, functions, and procedures that connect the website to the database so the two can communicate.
Table structure: description of tables, fields, field types, and field sizes for the whole system.
Index description: index specifications derived from searches and requests commonly carried out by the system, e.g., searching for clients using a client number or last name.
Request procedures: insertion, deletion, and update procedures for all tables in the database.
Demilitarized zone (DMZ): neutral area for exchanging files, normally shared by the external and internal users of a system. A DMZ prevents users from accessing the internal system.
Firewall: network security system that monitors inbound and outbound traffic in line with the security rules. A firewall acts as a barrier between a reliable internal network and an unreliable external network, such as the internet.
Connection models: user connection, verification, and authentication procedure.
Database query models: procedures for consulting the database to be used by all programmers.
Performance models: procedures aiming to improve system performance, to be used by all programmers.
Basic screen modules: functions that operate fields, buttons, and checkboxes on all screens of the system.
Basic report modules: functions that operate report components such as headers, footers, text body, etc.
Basic graphical modules: functions that display standard graphs such as XY graphs, pie charts, regression functions, etc.
How Does a Team Use Architecture Documentation?
So, you’ve put a team together, got the different company departments collaborating, and maybe even hired external service providers or consultants. How do you explain the solution and their tole to each person? This is only possible through detailed documentation.
Going back to the technical diagram above, you’d need to draw even more detailed diagrams of some of the key components. For example, the database driver and firewall would be described in more detail in their own comprehensive diagrams. Developers and designers can then use them to carry out their work.
Let’s Recap!
Documentation is an internal contract between the stakeholders and a communication tool that aids understanding of the system's heart.
Your documentation must be detailed and comprehensive. This will prevent misunderstandings and save time.
Documentation should be written for two phases: project proposal and project implementation:
General documentation of the architecture for the project proposal phase.
Technical and detailed documentation for the project implementation phase.
In the next chapter, you’ll see how to determine what your documentation should contain depending on who will read it.
