I am always posting provoking post on my Linkedin, and I have decided to replicate those here. Let's socialize!
Why do people mistakenly think that documentation is a critical success factor in software development?
Documentation should be concise: overviews/roadmaps/high-level diagram/guidelines are generally preferred over detailed documentation.
Never forget that developers rarely trust documentation, particularly detailed documentation because it's usually out of sync with the code.
You should understand the total cost of ownership for a document, and someone must explicitly choose to make that investment.
Ask whether you NEED the documentation, not whether you want it there as a security blanket
We certainly don’t need "just in case" documentation. We need just enough documentation to make sure the team is successful.
Your team's primary goal is to develop software; its secondary goal is to enable your next effort.
Documentation is a necessary evil; the project cannot survive without it. For this reason, we need to find ways to do just enough documentation — no more, no less.
Your team should classify the code as a major, if not the primary documentation of the software.
The rationale for the code being the primary source of documentation is that it is the only one that is sufficiently detailed and precise to act in that role.
Collaborative documentation
Collaborative documentation breaks away from the static nature of traditional docs. It's user-friendly, and, most importantly, interactive.
When a user encounters an issue or finds something lacking in the documentation, they don't have to wait for an official update. Instead, they can immediately add comments, suggest edits, or even directly modify the content. This not only ensures that the documentation is more accurate but also enriches it with diverse perspectives and real-world usage scenarios.
Confluence can be a great tool for collaborative documentation.
Top comments (0)