Introduction

I have seen multiple articles encouraging developers to quit documenting while creating a software. I believe this is the direct influence of the Agile Manifesto and a quite a misunderstanding (in case you haven't noticed it says comprehensive not any in there).

I tend to disagree that we can completely drop any form of documenting our work leaving the code to speak for itself. One exception I would accept, is really simple script, application or a webpage. In other cases we are going straight off the cliff.

Why, why, why?

Software development is a form of engineering and it turns out that in other industries engineers tend to produce quite an amount of documentation.

First of all, an engineer is only a part of a delivery chain. It is really rare that an engineer (or team of engineers) provides a final product. That said, ideas need to be somehow communicated, assumptions must be made and limitations must be discovered. What is the better way to think about them and share our discoveries than writing them down? For Pete's sake, we are solving a problem here and someone needs to understand and agree to our solution!

If you plan to maintain the project till the end of its life, then you probably need to revise your plans. What is more, there will be times, when you will expand your team and lack of documentation will cause spending more and more time explaining how your system works to new team members. Documenting your work may seem irrelevant and waste of time in the early phase, but a high level overview, and some guidelines, and tips&tricks will save tons of work later.

One last thing, there is an industry wide metric called the bus factor. It defines how many employees need to be hit by a bus to lost crucial part of knowledge. Do you really want to be left alone with a pile of code which you are not familiar with, having no idea where to start digging, while your customers demand fixing issues? All of that because no one cared to draw few diagrams?!

How much?

There is a corporate knowledge, the more paper the cleaner your ... or maybe we stop here.

The number of papers and level of details depends on multiple factors:

1. Industry

If you are dealing with avionics or automotive you need to produce zillions of documents and reports, some of which may be required by the external certification committees.

On the other hand, if you are doing simple web app, a single diagram may be enough.

2. Customer

Some customers require you to produce multiple reports from the development phase: design documents, test reports, performance reports, license compliance reports etc. Not much you can do about it.

3. Size of the project

Any complex system, may need documentation on multiple levels: general system overview, specific components documentation, internal APIs, public APIs etc.

Simple projects are usually good with the general overview.

4. Team structure

If you work with localized team with great rotation of team members or your team is spread across multiple locations, you may want to create overviews, guidelines, wikis etc. It is really wasteful to start every quarter of a year with giving new members training on basics.

Summary

I know that maintaining documentation is troublesome, but that is why I am not asking to document all the code, with all the internal APIs, etc. Especially, when cooperating within a small team or small scale project. The minimum we should be doing is to note down what kind of problem we are trying to solve, and how our software is going to help us. Then architecture overview, few diagrams may be enough.

Writing down ideas will give us time to re-think possible options and get feedback from others.

Let’s not be scared, few papers won’t bite.