Software documentation as a guidebook

A different approach is needed

"Working software over comprehensive documentation" is what the Manifesto for Agile Software Development says and it's incredible to see how many software teams have interpreted those five words as "don't write *any* documentation". The underlying principle here is that real working software is much more valuable to end-users than a stack of comprehensive documentation but many teams use this line in the agile manifesto as an excuse to not write any documentation at all. Unfortunately the code doesn't tell the whole story and not having a source of supplementary information about a complex software system can slow the team down as they struggle to navigate the codebase.

I'm also a firm believer that many software teams have a duty to deliver some supplementary documentation along with the codebase, especially those that are building the software under an outsourcing and/or offshoring contract. I've seen IT consulting organisations deliver highly complex software systems to their customers without a single piece of supporting documentation, often because the team doesn't *have* any documentation. If the original software developers leave the consulting organisation, will the new team be able to understand what the software is all about, how it's been built and how to enhance it in a way that is sympathetic to the original architecture? And what about the poor customer? Is it right that they should *only* be delivered a working codebase?

The problem is that when software teams think about documentation, they usually think of huge Microsoft Word documents based upon a software architecture document template from the 1990's that includes sections where they need to draw UML class diagrams for every use case that their software supports. Few people enjoy reading this type of document, let alone writing it! A different approach is needed. Read more in "Software Architecture for Developers"...

About the author

Simon is an independent consultant specializing in software architecture, and the author of Software Architecture for Developers (a developer-friendly guide to software architecture, technical leadership and the balance with agility). He’s also the creator of the C4 software architecture model and the founder of Structurizr, which is a collection of open source and commercial tooling to help software teams visualise, document and explore their software architecture.

You can find Simon on Twitter at @simonbrown ... see for information about his speaking schedule, videos from past conferences and software architecture training.

Re: Software documentation as a guidebook

I'm with ya, totally agree. Any suggestions? How do we fix this problem and educate those that are willing to listen that some documentation is a good thing?

Personally, I'm a fan of TomDoc and have been using it in my code for several months. It's clean, clear and a good guide to build from.

But I'm not sure that's the answer. Maybe automated docs are a better alternative?


Re: Software documentation as a guidebook

A trick is not to think about documentation per se but to come at it from the business value equation. Think about the people who have a "job to be done" and then figure out what is the best solution for their problem. In the default instance it will be working code, for other jobs it might be some form of documentation. For example, "As the support engineer I need a description of the architecture so that I can find and fix interface bugs". Put those user stories in the backlog and prioritise appropriately.

Re: Software documentation as a guidebook

very nice book , it helped me lot to think differently in software perspective,many developers never think about architecture ,they simply jump into code level.It will be more beneficial if author could add some essay related software code documentation.

Add a comment Send a TrackBack