Skip to main content

Comprehensiveness of documentation

Documenting a software project is always one of those chores nobody wants to do. For programmer the code itself serves as a documentation .An accurate one unlike the separately written one which is always out of date anyway. Non-technical persons also wouldn't understand the technical documentation much better than the code itself.

Same goes with the architectural drawings. They are just rough scetches of the system. Higher level they don't give much new information and drilling down wouldn't give an accurate picture until you go down to the code-component level. Which would still be out of date whenever the code changes.

But that's exactly what so many software projects get wrong. You don't need to document the obvious. The code itself can be enough documentation as long as it's clear and well written.

It's the why's that need to be written down! Looking at the code it's easy to tell what it does but it might not always be apparent why it does what it does. That information alone can give a lot more insight than pages of technical descriptions and diagrams describing the flow of code. The why is easy to reimplement, the code can be thrown away when you know what is it for.