Home > technical > Working Code Over Comprehensive Documentation

Working Code Over Comprehensive Documentation

Comprehensiveness is the enemy of comprehensibility – Martin Fowler

Martin’s quote may be the main reason why this preference was written into the Agile Manifesto

Working software over comprehensive documentation

Obviously, it doesn’t say “Working software and no documentation“. I’d bet my house that Martin and his fellow colleagues who conjured up the manifesto intentionally stuck the word “comprehensive” in there for a reason. And the reason is that “good” documentation reduces costs in both the short and long runs. In addition, check out what the Grade-ster has to say:

The code tells the story, but not the whole story – Grady Booch

Now that the context for this post has been set, I’d like to put in a plug for Simon Brown’s terrific work on the subject of lightweight software architecture documentation. In tribute to Simon, I decided to hoist a few of his slides that resonate with me.



Ad Hoc Docs

Note that the last graphic is my (and perhaps Simon’s?) way of promoting standardized UML-sketching for recording and communicating software architectures. Of course, if you don’t record and communicate your software architectures, then reading this post was a waste of your time; and I’m sorry for that.


  1. April 8, 2013 at 8:49 am

    I think a big advantage of Simon’s approach is that it concentrates on communication. I’ve seen too many who use UML concentrate too much on being syntactically correct (leading to too much detail and mixed abstraction levels). By the same token, I’ve seen people who don’t use UML because they think it can’t be used if it isn’t being done “right”. This leads to their going completely ad hoc (and having a harder time communicating).

    • April 11, 2013 at 7:25 am

      Yeah, I think you’re right Gene. Communication first, representation second.

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: