Let’s continue to consider the software architecture. After we recognized stakeholders, functional and non-functional requirements, it is time to document the results. That is why, in this article in the series, we consider the principles of working with architectural documentation.
But before to dive deeper with individual cases, I would first like to note what we will consider as architectural documentation. Unfortunately, there are no standards in software architecture that need to be followed when creating documentation, such as, for example, in architecture of buildings. In addition, each company may have its own rules for writing documentation, which you also need to follow. In this article, the architectural documentation will be referring to the high-level description of the system, showing its basic principles of work. The main purpose of this documentation is to correlate functional and non-functional requirements.
Why do we need software documentation
Before describing how to properly create architectural documentation we need to understand why it is needed.
There are three basic goals for architectural documentation:
- Knowledge sharing. It is suitable for knowledge transfer between people working in different functional areas of the project, as well as for knowledge transfer to new participants.
- Communication. Documentation is the starting point for interaction between different stakeholders. In particular, it helps to share the ideas of the architect to the developers.
- Analyses. Documentation is also a starting point for future architectural reviews of the project.
And of course, the key question that related not only to architectural documentation, but to any documentation in general, it does not matter be it project documentation, developer documentation, etc — when it is worth starting to create and maintain documentation. To answer this question there is a short formula:
(Cx — Cy) > Cdiff
where
Cx = The cost of the project without documentation,
Cy = The cost of the project with the documentation,
Cdiff = The cost of maintaining documentation.
Using this formula it is also easy to calculate what exactly documentation you need to create, how often it is needed to be updated, and other similar questions. It also answers the questions of whether documentation is needed in small-size projects, long-term or short-term, and so on.
And how it can be that a project’s cost without documentation be much higher that a project with documentation? Just imagine that you have a project for 200 developers, lasting 5 years, with average period of developer’s work on a project which is equal to 2 years. Without documentation, it will be pure chaos, even for doing minor changes. A few tips on how to maintain good documentation are listed below.
Types of diagrams
Let’s consider what types of architectural schemes and diagrams exist that can be used in the documentation:
- Informal. The most common type of diagrams. May be represented in any form. Often acts as the easiest and fastest way of communication between stakeholders. Among the disadvantages — it is almost the same to understand or to be confused, that why it is required a detailed description of the diagram.
- Semiformal. It is a standard graphical scheme or diagram that has certain rules of creating. Among the disadvantages, it does not provide a complete description of each specific element, therefore it requires knowledge of the semantics of the specific diagram. Also, an additional software is required to create these diagrams. And each scheme is usually focused on a single attribute. UML diagrams are semi-formal, as well as certain approaches for creating diagrams, for example https://c4model.com/ or https://en.wikipedia.org/wiki/4%2B1_architectural_view_model.
- Formal. It is in some form a language for describing architecture. Allows to make code generation directly from the created schemes. Actually, it is more suitable for hardware system engineering. Among the disadvantages: it requires special software and knowledge, both for writing and understanding. Example: https://en.wikipedia.org/wiki/Architecture_Analysis_%26_Design_Language
Tips for writing documentation
At work, I often have to write documentation or maintain it. Therefore, I developed several basic principles for writing it:
- Avoid repetitions. DRY principle (Don’t Repeat Yourself) works equally well as in programming and in documenting architecture. Create links, but do not write the same thing several times.
- Recognize for whom you are writing. Perhaps the most important rule. Documentation for developers and top management may differ dramatically. Therefore, it is necessary to decide for whom you are doing this, then understand what these people need in your documentation and what answers they will try to find.
- Avoid ambiguity. In my practice, one of the most frequent problems with documentation. For example, you came up with a solution which is documented in the form of diagrams. You understand it, you know the context, but the person who will read it may not know it and will be confused what exactly you had in mind. Therefore, you should always provide context for your diagrams as a description. And also, try to use standard approaches. For example, I really love using C4 (https://c4model.com/) to describe my solutions, due to the fact that this approach allows you to first make a high-level description of the system, and then dive into the details at the level of components, containers and deployment, and also has fairly formal criteria for describing each element.
- Maintain relevance. In this case, you should find a compromise between time spent and relevance. Here you can again use the same formula which is described at the very beginning of that article. If maintaining of documentation is cheaper for a project than opposite way, then it is right thing to do.
- Review documentation. You should periodically review the documentation. So you will most likely find places that have lost relevance and are worth updating. And also, try to share documentation with stakeholders and ask for their opinion. This is especially useful when you are starting to document architecture.
Popular tools for creating diagrams
Let’s consider what you can use for creating diagrams, schemes, except of the standard whiteboard:
- MS Visio (https://en.wikipedia.org/wiki/Microsoft_Visio ). It allows you to do almost everything that is possible. One of the minuses — does not work on mac OS. And paid.
- Omnigraffle (https://www.omnigroup.com/omnigraffle/ ). It is for mac OS users. Also paid.
- Enterprise Architect (https://sparxsystems.com/products/ea/ ). It is paid, but there is a 30-days trial period.
- And my favourite, fast, simple and online tool draw.io (https://draw.io ). Supports third-party plugins, ranging from C4 to AWS specific. You can do anything as you wish on any platform. Ideal as a whiteboard tool for creating informal diagrams. And free!
No comments:
Post a Comment