Smart Documentation

We've been documenting for years. We document every engineering system we develop, every software we write. Even before we realized we needed to manage knowledge, we recognized the importance of educating others about documentation. If we don't document, how will we maintain? We asked.

Are we documenting smartly?

Does this documentation truly serve the programmer (or any other professional) when they return after two years to make changes?

It's easy to examine the level of documentation in retrospect: Did the maintainer indeed succeed in understanding the modules well? Was a supplementary oral explanation needed to understand it? Was it necessary to consult the original developer personally to get tips and guidance on pitfalls?

In most cases, the answer won't bring peace to minds. The reason for this is simple. In most cases, we document the obvious. We document the known. We document the straightforward. We don't explain why a certain line is written in a certain way after much blood, sweat, and tears.

A simple mechanism can help with this issue. The project manager should examine not only the existence of documentation, but also its quality. They should ask the developers several questions:

• Where did you encounter exceptional problems?

• Where did you get delayed more than expected?

• Were there interesting tricks to bypass problems?

These questions and similar ones highlight areas and topics that necessitate specialized documentation.

Very simple. Everything starts and ends with awareness.

---

Want to learn more about document & content?

Here are some articles you might find interesting:

• Content Processing

• Has content become a secondary component of websites?

• Content Management, Content Manager, and What's Between Them