Documentation in Software Architecture

Nikolay Ashanin
Jan 14, 2019 · 5 min read
Image for post
Image for post
Image 1. Monument valley game

Let’s continue to consider 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.

However, before to dive deeper with individual cases, I would first like to note what we 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 the architecture of buildings. Also, each company may have its own rules for writing documentation, which you also need to follow. In this article, the architectural documentation is referring to the high-level description of the system, showing its fundamental principles of work. The primary purpose of this documentation is to correlate functional and non-functional requirements.

Article series

  1. Stakeholders in Software Architecture
  2. Types of Software Architects
  3. Quality attributes in Software Architecture
  4. Documentation in Software Architecture
  5. Certificates in Software Architecture
  6. Books in Software Architecture
  7. System Design Cheat Sheet

Why do we need software documentation

There are three primary 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.

Of course, the critical 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. There is a short formula to answer this question:

(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.

It is also easy to calculate what documentation you need to create, how often it is required to be updated, and other similar questions, using this formula. It also answers the questions of whether the documentation is necessary for small-size projects, long-term or short-term, and so on.

Moreover, how it can be that a project’s cost without documentation is much higher than a project with documentation? Just imagine that you have a project for 200 developers, lasting five years, with an average period of developer’s work on a project which is equal to 2 years. Without documentation, it is pure chaos, even for doing minor changes. A few tips on how to maintain proper documentation are listed below.

Types of diagrams

  • 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.
Image for post
Image for post
Image 2. Informal diagram example (https://en.wikipedia.org/wiki/Load_balancing_(computing) )
  • 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, additional software is required to create these diagrams. Also, 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.
Image for post
Image for post
Image 3. Semiformal diagram example (C4 deployment diagram example from https://c4model.com/img/bigbankplc-LiveDeployment.png )
  • Formal. It is in some form a language for describing architecture. Allows making code generation directly from the created schemes. 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

  • 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 it, then understand what these people need in your documentation and what answers they try to find.
  • Avoid ambiguity. In my practice, one of the most frequent problems with documentation. For example, you came up with a solution that is documented in the form of diagrams. You understand it, you know the context, but the person who read it may not know it, and it confuses him what exactly you had in mind. Therefore, you should always provide context for your diagrams as a description. 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 first to 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 reasonably 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 documentation is cheaper for a project than the opposite way, then it is the 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. Also, try to share documentation with stakeholders and ask for their opinion. It is especially useful when you are starting to document architecture.

Popular tools for creating diagrams

Recommended books

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store