CODEX
Why You Shouldn’t Use Confluence for Code Documentation
It’s always out-dated
Most of us have been there — it’s almost a rite of passage: following a guide in Confluence that is horribly out-of-date. The person that wrote it took great pride in its detail at the time of creation, added plenty of screenshots, and maybe even some animated images. Unfortunately, the menu bar in the screenshot no longer exists, and the button required by one of the steps has been removed.
Confluence and wikis become out-of-date quickly
Developers work in code repositories, not Confluence. Unless they update documentation on every change, a single user story could make it stale. They may not be aware that the documentation exists in some cases.
Over-explanations
Adding a simple feature to a complex, unknown system can be overwhelming, especially when reading a research-paper-sized article on architecture. Some authors pack pages with detail, which is a noble endeavor. However, when you want information fast, tracking it down can be tedious. Too much information can create unnecessary confusion.
Under-explanations
On the other side of the spectrum, lacking documentation can inflate a feature’s scope. Sometimes developers, especially in a hurry, take short-hand notes that only they understand. The notes serve as a convenient reference for them but are unusable for someone taking over a project. In these situations, the cost of developers leaving increases.
Repeating unowned documentation
Sometimes people document needlessly. For example, explaining how to integration with third-party libraries. Usually, that information is readily available on the third-party’s website.
Diagrams
Confluence is not geared toward architecture diagrams. Because of that, developers outsource images to external editors, exporting and pasting png files. These diagrams can be elaborate, with dozens of nodes. They rarely get updated after their creation, especially when the author no longer works at the company. Nobody wants to go through the hassle of recreating it from scratch.
Technical Requirement Documents (TRDs)
TRDs describe how a feature will be implemented. They show thought processes, list alternative solutions, and record conclusions. Taking note of code decisions is a great idea, but there are better ways to do that in the code repository.
In practice, TRDs can be useful for an immediate need to improve collaboration but become clutter after the corresponding features are released. Sometimes developers spend more time writing and updating them (to please the process) than it takes to implement the feature.
Too many documents
Many wikis have the same issue: myriad documents created all around the same time, followed by a large gap in time. When companies first introduce wikis, there is a rush — possibly an initiative — to document everything neatly, like moving furniture into a new house. However, just like moving, some boxes don’t fit nicely with the others. They are eventually unpacked weeks later or get thrown into a storage closet.
The wiki may have visible fatigue: rich, organized documents alongside unfinished ones littered with TODOs.
No peer review
Code can be scrutinized in review for accuracy, and automated processes reduce the chance for human error. Wiki documents, if internal, don’t usually go through review. Accuracy of information, spelling, and grammar are solely the author’s responsibility.
Developers don’t use it.
Search engines like Google and Bing are developer’s friend. They’ll land on websites with official documentation, peer-reviewed source samples, or upvoted answers to questions like StackOverflow. Confluence is the last place to look unless the knowledge is strictly internal, or they know it exists for many people.
Conclusion
Documentation is not bad; it’s just not the right place for code. Code documentation should live next to the code in a place where the developers frequent.
