Good documentation is the foundation of a good project.

Documentation is not just about explaining how something works. It also includes requirements, presenting the product from the customer’s point of view, and other non-technical elements.

In the world of apps and the consumer market, it is easy to imagine how a customer uses a particular product. However, when dealing with specialized products that may not have everyday applications, it becomes difficult to fully understand the customer’s perspective. In these cases, there are many less obvious aspects that need to be documented.

Bad example

Here’s how it often looks.

Self-organizing teams working in an agile, quick, and efficient manner are confident about their abilities and don’t prioritize documentation.

At the start of a new project, everything goes smoothly. The engineers are focused, creating the product rapidly, and anticipating great profits.

Once the product is released and selling well, the work continues. However, there may be some team rotation, growth, or division into smaller teams. In a different part of the world, a completely new team is formed.

New engineers have no idea how to approach their work. The old engineers have their own tasks and don’t have time to help the new ones. In the end, it turns out they can’t continue their work because they’re waiting for what the new engineers were supposed to deliver.

Frustration sets in as everyone realizes that it doesn’t make sense to continue work in this way.

Conclusion

No one needs documentation until someone needs it.

Why?

Creating documentation in real time has many advantages. Besides the obvious benefit of sharing knowledge, documentation can also serve as a verification step. If something is difficult to document, it is likely too complicated.

Standard

Organizations should establish documentation standards and provide training in this area. This is the best way to ensure that everyone knows what to do and where to find information.

Scope of documentation

I believe documentation should cover an adequate range of topics – not too many and not too few. But how do you determine when it’s enough? That’s the question.

Requirements should definitely be included in the documentation scope. By that, I mean they should be documented and easily linked to the rest of the documentation.

From General to Specific

The content of the documentation should guide the reader in a way that keeps their interest. Technical details should be presented separately from general system descriptions.

Tools

Everyone needs to know how things are done. It can’t be that each team does it their own way. It can’t be that engineers constantly explain to managers how to access documentation. It can’t be that you have to wait several days to access a document, otherwise you can’t work.

Many times I have come across a website that answers all my questions, but I have found it too late. Wiki systems and other collaboration tools are not yet good enough to facilitate this.

It is still the responsibility of people to share the knowledge.

While wiki pages offer certain advantages, they also have their drawbacks. Anyone can make modifications, but often, only a new version is saved. What happens after that is somewhat out of the author’s control.

And many pages have no future because no one knows they exist.