For a Coherent Software Product… Draw More Diagrams

Pencil, By Juliancolton (Own work) [Public domain], via Wikimedia Commons

Unless you’re building it entirely on your own — and even sometimes then — for a unified and coherent software product, you need prominently-shared diagrams of what you intend to build.

Most software products are built by more than one person; more than one mind. Most are built by more than one team and usually across more than one skill or discipline. That’s many backgrounds, many viewpoints… but still one intended product in which they all need to be unified.

No-one would imagine coding an API without a spec, yet we often build systems without a diagram of the architecture, components, boundaries or intended flows. Retrospective diagrams often never happen, or happen way beyond the point it became painfully obvious they were needed. We over-rely on the verbal signs that we are aligned, without backing it up with a diagram.

Without a shared vision of the intended outcome, we’re likely to translate any purely verbal descriptions into different mental models, and onwards into different technical solutions… which then need to be aligned. “Oh I didn’t realise”, becomes all too common. This is particularly true in places where multiple disciplines overlap: Product owner, UX, front end, back end, operations, marketing, etc.

Everyone sees their piece of the puzzle, but diagrams confirm how they will all fit together. Without them, we introduce opportunities for hidden agendas and unnecessary extras to creep in. Human nature dictates that, where ambiguity exists, we tend to work silently to our own preferences rather than seeking a unified team answer. A diagram can provide that answer, or at least highlight the blank space in which it needs to go.

What to draw?

Whatever you find yourself discussing… but especially user interfaces, architecture, components, flows, and absolutely all inter-team or component boundaries.

How many drawings?

Just enough… but at least the highest levels of the product, then break down where more clarity is required and particularly where team boundaries exist.

Not too many though… or no-one will look at them. Find a happy balance.

What to draw with?

Informality, and a shared medium… Keep diagrams informal, because speed is important in encouraging capturing of info. Use a tool for more formal diagrams, but a tool that everyone can access; the person drawing the diagram will not necessarily be the only one changing it or adding to it later.

Where to draw them?

Visibly! Stuck away in a repository or a wiki where people rarely (or begrudgingly) go, diagrams are next to useless. Get copies of them on up on the walls too.

Update them!

An obsolete diagram is worse than no diagram. Think living diagrams!

When a change arises, update the diagram now, even if only with a scribbled annotation on a printout to be added to the original later. This is why informality often wins; there is no pristine copy that needs painstakingly updating.

Assign someone the action of updating the diagram, and make sure that they do.

Encourage diagrams

Make sure whiteboards are available, with pens (if you have to hunt, the moment will pass). Also make sure wall space is available, on which to stick diagrams that will live for longer.

Whiteboards aren’t just for visual disciplines; encourage engineers to draw components, flows and architecture too. Even short-lived diagrams, such as those drawn in one meeting, can unify people at a point in time. Get everyone comfortable with the idea of standing up with a whiteboard pen… and drawing. It should be a daily occurrence.

There should be a blank whiteboard usable by anyone who feels the need, at any time, and preferably within reach. This is a cheap resource, so over-provide. The improvement in communication, and in a coherent product, will be worth it.

Leave a Reply

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

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

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s