Maintain Documentation Successfully
In our previous Shortcut we looked at what makes good documentation. Unfortunately, writing good documentation is only part of the story. Just as our software evolves and changes, the documentation also needs to do so in parallel.
I’m sure you will have encountered documentation that is out of date—code comments that no longer reflect what the code does, or API docs that have missing methods or relate to a version of the software that no longer exists. It is extremely frustrating for users of your product or API to discover, when they urgently need to do something, that the documentation either tells them the wrong thing or can’t be found at all. In the case of a major outage, it is also expensive.
Treating documentation as a product and linking it to the release cycle works well where releases are infrequent, but breaks down in cases where you have multiple small releases to production every day. Unfortunately maintaining documentation is one of those areas where the state of the art has not kept pace with modern development practice. Thankfully, companies such as Google and the Financial Times have shared their ideas around ownership, automation, and more, so along with my own experiences we’ll look at what we can learn from them in this Shortcut.
Ownership
Documentation often feels like something that no one is responsible for because everyone shares responsibility for it. But in the ...
Get Maintain Documentation Successfully now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
