Code hardly every adequately documents itself. Nobody in their right mind wants to learn a complex new system architecture by being presented with an IDE and a link to github. Good documentation is an essential part of any maintainable system.
Good documentation often starts as scribblings on a whiteboard, but if an artefact is useful, it is worth being captured more permanently (even if that's just a photo on a wiki).
Speaking of wikis... just because it's easy to create a page, doesn't mean you should!
Good documentation helps to communicate important ideas.
Good documentation remembers what we tend to forget, particularly reasons for decisions.
Good documentation aims to be just in time and just enough.
Good documentation is useful, which means it has to be accurate and relevant.
Good documentation is owned and looked after. If you remember nothing else of this rant, remember this.
Good documentation is not redundant.
Good documentation knows when it is none of these, and should be archived for the historians.
Top comments (0)