concept documentation in category legacy software

This is an excerpt from Manning's book Re-Engineering Legacy Software. Login to get full access to this book.

Given that the project spans multiple generations of developers, it would seem that keeping accurate and thorough documentation is essential to its long-term survival. Unfortunately, if there’s one thing that developers enjoy less than writing documentation, it’s keeping that documentation up to date. So any technical documents that do exist must invariably be taken with a pinch of salt.

If you want to keep your project healthy, don’t focus only on the source code. Documentation, toolchain, infrastructure, automation, and the culture of the team are all important.

Ask any developer if it’s a good idea to share knowledge with their colleagues about the software that they work on, and of course they’ll agree that it is. But when it comes down to the nitty-gritty of sharing information, most developers are pretty bad at doing so. They don’t enjoy writing and maintaining documentation, and they rarely share information with colleagues through other means unless they’re prompted to do so.