The scourge of Document Driven Design

Documents, or rather words are the scourge of product design. Because words can never convey the true meaning or emotion of what is really required. All to often, software development projects are driven by the documentation – agile projects can be equally guilty of this- driven by words on paper (or card) that convey what the requirement is. Issue #1. Developers don’t read!

Except for a few exceptions, software is all about a user interacting with a system in order to accomplish a goal. Trying to describe that premise in terms of features and functionality is fundamentally flawed as it will be nested in the language of technical implementation, not in the user interaction. “Find” becomes “search”, “buy” becomes “shopping cart”, “check” becomes “validation” and so on. Issue #2. The desired outcomes become lost in a smog of technical jargon.

Solution: Picture Driven Design. Up front. Yeah! I’m all for up front design! A picture tells a thousand words. It has the power to remove ambiguities, clarify the vision, showing what the journey to realise outcomes look like. Start with a day in the life of… scribble out the flow, the user journey. Nothing complicated, boxes and arrows. Then scribble out what the user interface might look like. Done. That’s your up front design. That’s your documentation. That’s your scope. What you do next is up to you, write loads of documents that describe it and produce the software in a waterfall way if you want. I’d prefer you were more lean and adopted agile practices, but whatever you do, start with the picture. I’m convinced it will save much pain later on.


  1. Vijay Patel · Tuesday, 22 July, 2008


    Have to agree on the sentiment. Document Driven Design can seriously knock agile projects out of kilter (especially when the client changes their mind about what they originally wrote! I don’t think developers like surprises…)

    I always used pictures to convey ideas, and came to this realisation: it’s the *motion* of drawing arrows and boxes that helps people understand; not always the drawing itself. I sometimes find myself re-drawing the same picture for different audiences. Making these processes interactive always yields the best results.

    In fact, our Domain Modeling tool was created to end this scourge 


  2. Prashant Gandhi · Tuesday, 29 July, 2008

    All the crows that I have seen are black. Hence, all crows must be black.

    Yes, empirical evidence does point to “picture saying a thousand words” and I do think its true. But one must not disregard the power of written word. You and I write using words. Your blog is a set of words, not pictures. People still read it. Just as you can have badly written documents, you can have badly drawn diagrams as well and they can be equally frustrating.

    The difference, if you like, lies in the ability of the author to address his/her audience. And I dont even think pictures are the best medium. I find that videos and audios are probably more powerful medium to capture important concepts. Would you go through a powerpoint deck with pictures or look at a 3 minute video with commentary from the SME where they explain a difficult concept ?

  3. A A picture tells a thousand words. So prioritize pictures not words | dancingmango · Friday, 21 August, 2009

    […] That didn’t take long did it, and it looks like an initial release candidate. We’ve defined our scope in a way that we do not believe we can cut any more.  Any less functionality would not be a meaningful release.  Now we can get down to writing the stories, focusing our effort on something we are agreed looks right.  We’ve prioritized pictures, outcomes over words; Picture Driven Design. […]

  4. Jon · Sunday, 25 September, 2011

    This is old, but because it’s indexed so highly on Google, it’s important to post this:

    Dear blog author,

    Please learn English. “Document” does not solely imply the use of “words” alone. Your premise is faulty and therefore your entire post is based on a misunderstanding of a basic concept and can be disregarded.

    Pictures, diagrams, and everything in between, are also “documents”. A document is form of communication committed to “paper” (or disk, in the case of electronic communication). Wikipedia seems to agree. This is exactly why DDD is so powerful, because it’s not just about words, but about all documents. If they just meant words, they would have called it “Text Driven Design”.

    Again, please fact check your terminology before spewing your opinion so irresponsibly on the internet.

Leave a Reply