Design Documents Need Pictures

When I do assessments, I ask for lots of project documents and data. A few years ago, I was working on an assessment for a very large system, so I asked for an architectural picture. I was surprised--this million plus LOC system had no picture at all. No wonder it was so hard for the people to plan, organize and execute their work.

I've had the opportunity to look at design documents recently. Many of them have only words. No data flow, no picture of how this piece of the system works, or how this piece of the system fits into the bigger system.

Now, I'm no artist. I've discussed my phobia about pictures before. But I've realized that if I can't draw a picture of a complex problem, I probably don't understand it well enough to solve it.

If you're implementing by feature and working with a large group, an initial cut at a design, whether it's a whiteboard discussion or a design document, might be a useful technique to help people head in a reasonable direction. But don't think words are enough. And if you're working in an Agile team, you may not need a document at all, but you will need a picture.

Draw a picture. You'll find people are able to see the design better than they can read it.