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.