Article: The Idea Behind the Documentation

[igr]

Why do we write documentation? What is the purpose of the documentation? What is the right amount?

The article would address the following points:

• Write documentation before the code (Documentation Driven Development)
• Documentation should serve to fill the gap in communication
• Documentation is everything: UX, API, code, decisions.
• Write testable documentation.

Read article here (translated using Google translate)

[igr]

THE IDEA BEHIND THE DOCUMENTATION

Documentation is probably one of the most underestimated practices in software development. Somehow we all agree that documentation is a necessity, yet we end up something that is more a burden than a valuable artifact.

Why do we write the documentation? More specifically, what is the purpose of the documentation that brings the value to the project? In my understanding, it's this:

The documentation serves to resolve the lack of communication.

The program code, user interface, infrastructure decisions... everything communicates with a human in a certain way. The code speaks with the syntax of the programming language, the user interface talks with visual symbols and text, etc. Such conversation with the machines is far from perfect. Computer systems may be too complex to be understood with limited communication means. That makes the fully understanding impossible. The documentation is the super-hero that fills this insurmountable gap.

When we treat the documentation as something that fixes the lack of communication, it becomes easier to figure the right amount of it.

For example, if the user interface fails to communicate what is happening on the screen, a documentation needs to explain that. If the code, despite all the patterns and practices, fails to communicate with the developer, the documentation must give additional clues. If the project does not follow the infrastructure standards, a document describing that is required. On the other hand, documentation does not need to describe the obvious patterns and standard procedures. The clean code, understandable UI, widely accepted standards - they dont need to be described at all.

Finally, the documentation must become a full-fledged artifact of a software project. Our duty is to maintain it correctly: to be minimal, pragmatic, updated and valuable. Otherwise, it is not a documentation.