Concerned about the lack of documentation in your project? You are already (over)doing it

If you are in a SW project which lacks proper documentation, most probably you are already over-documenting.

Documentation is communication, and communication is constantly needed throughout the development of a SW:

  • You need to explain your design to your business stakeholders so they can provide feedback about whether this design will satisfy the business goals.
  • You need to tell your developers how to refine and implement the design.
  • You need to explain the design to the testers so they can find out how to test.
  • You need to explain to the management why something is not working, or what can be implemented easily in the next version, or what would incur major cost and risks.
  • You need to tell the vendors how their components should behave to fit to the design.
  • You need to discuss with HW colleagues what the SW design should expect from the HW and vice-versa.
  • You need to discuss with the operation (or DevOps, these days) team how the SW should be deployed and operated.

You will need a written piece of description to be able discuss matters of such complexity anyway. If you have proper design documentation, you can use this documentation in each of these discussions. If you don’t, you’re going to have to write long emails or meeting minutes for each of these discussions, and again for each new question. From this picture, you can do the math yourself to calculate the ROI of proper documentation.

However, benefits do not stop at that.

A proper documentation in contrast to a dozen emails scattered over the past two years brings an additional benefit: a consolidating perspective. In each of the discussions named above, you’ll bring in different aspects into your design. And a consolidated document will highlight the non-matching, non-converging aspects glaringly, so you can work on them and make your design converge to a vision with conceptual integrity.

In extreme cases, I have even seen the different aspects of a design artifact discussed in two mutually exclusive groups so one group could learn what the other group was up to only by chance. So a single document will ensure ownership of the design.

A single document will also allow you to see the gaps. An unaddressed part of the design will also be unaddressed in the document, and this cannot be identified in several emails.

A single document will also be more reusable in the future. First, it will be easier to find, as emails are lost with people when they are gone, even if they stayed, finding an email might still be a challenge. Secondly, its scope will be clearer to future team members even if nobody from the original team remains. And lastly, the document will have a complete view of the problem domain (requirements, constraints) and the solution domain. Without documentation, the solution domain can still be reverse-engineered from the implementation, but it’s much more difficult to deduce requirements from the design.

You might argue that not all the different stakeholders mentioned above would be interested in the same content, and you’d be right. For this, your document should have views targeting specific stakeholders. The 4+1 model by Kruchten is a solid start, but you can always invent new views (e.g. test view, HW view) as needed.

So, if you find yourself or your team writing multiple long emails (or meeting minutes) on similar subjects; identify the subjects, collect the emails you’ve written so far, and consolidate them into a design document. The additional effort will be ~10%, but the benefits will outweigh that by far.

2 thoughts on “Concerned about the lack of documentation in your project? You are already (over)doing it

  1. Actually, today nobody should have to write emails anymore. I don’t want to take your valid point away, but using collaboration platforms like GitLab or specific chat software like slack to communicate with the team and share information is making it much more efficient and easy to find the information for everyone. Word documents should be avoided in favor of web based documentation which is close to the code and easily accessible and modifyable for anyone. E.g. we write all the documentation in markdown.

    Important topic and well written article!

    1. Many thanks for the comment, Kaspar. As you point out, the tools have changed & improved. I think the essential difference remains: long-term consolidated communication (documents, whether Word- or Web-based) vs. short-term communication on specific topics. If one type of communication is lacking you have to compensate a lot in the other type.

      The short-term communication is also indispensable. For example, the Apollo program of NASA is well-documented, but today’s engineers would still not be able to re-implement the program just on this basis. Naturally a lot of short-term communication was necessary in addition to the documentation to send the astronauts to the moon.

Leave a Reply

Your email address will not be published. Required fields are marked *


This site uses Akismet to reduce spam. Learn how your comment data is processed.