How documentation can improve everything
Today, I want to discuss a big benefit of writing documentation that is often ignored: driving improvements to confusing and convoluted solutions.
And by documentation, I really mean all kinds of documentation you can find in software development:
Source code documentation
API documentation
Design and architecture documentation
Process documentation
User-facing documentation
…
When you try explaining something to someone else, the flaws and gaps become obvious:
If you dislike explaining how the combination of five parameters works together in a function signature documentation, perhaps you are missing a better abstraction in the code to express the complexity.
When writing a tutorial on how to use your external API to achieve a common use case takes several API calls, maybe the right solution is to add a use-case-specific endpoint.
If the documentation for handling tickets is 10 pages long, perhaps the process should be simplified.
Describing how to run a development environment using three commands is not fun. Just make a better entry point to the project.
All these examples show that it doesn’t matter what the documentation is for. The process of writing documentation can trigger a re-evaluation of the solution itself, creating a continuous feedback loop: Document → Identify problems → Improve.
The ultimate goal is a solution so well-designed that its documentation becomes minimal and more self-explanatory, but to achieve this, it's often necessary to document the initial, more complex version first.
—Petr