Agile Zone is brought to you in partnership with:

Simon lives in Jersey (Channel Islands) and works as an independent consultant, specialising in software architecture, technical leadership and the balance with agility. Simon regularly speaks at international software development conferences and provides consulting/training to software teams at organisations across Europe, ranging from small startups through to global blue chip companies. He is the founder of "Coding the Architecture" (a website about pragmatic, hands-on software architecture) and the author of "Software Architecture for Developers" (an e-book that is being published incrementally through Leanpub). He still likes to write code too, primarily in .NET and Java. Simon is a DZone MVB and is not an employee of DZone and has posted 36 posts at DZone. You can read more from them at their website. View Full User Profile

Software Documentation as a Guidebook

  • submit to reddit

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"...

Published at DZone with permission of Simon Brown, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)