Diagrams as Software Documentation – When a Picture Says it Best

Software documentation is all too frequently overlooked or becomes irrelevant, lost in the inevitable wave of change. Accurate documentation requires not only thought and execution, but maintenance, as reality changes.

One form of documentation that is too frequently overlooked is a diagram.

What type of diagram should I use?

There have been many attempts at standardizing software design diagrams, such as UML, blech! Just typing it makes me cringe. Many times, as soon as you decide on a specific type of diagram, you find it hard to express what you are thinking within the restrictions of the diagram you are creating. In my experience, the diagrams that are easiest to create and understand are very free form, and well…fun!

When should I consider formalizing something?

The best diagrams tend to come from scribbles someone makes to aid explaining something and talking about it among a group. Much like when writing software, the thing that should trigger you to formalize your scribbles is noticing yourself redrawing the same thing more than once.

What tools should I use?

The best tool to use for your documentation is your imagination. There are tons of tools out there, and many are free, but you should primarily use something that feels comfortable so that your ideas can flow more freely and you can enjoy the experience. If you spend too much time fighting the tool you are using, frustration sets in and creativity is stifled.

What level of detail should I provide?

Keep in mind that usually, less is better. It is far too easy to clutter up your diagrams with more details and get all obsessed with it. Keep in mind though, that you are trying to help others visualize a system. Too many details lead to overload and can be very distracting.

The best way to figure out what to include is to explain the diagram to others. It is especially helpful to explain the diagram to someone else as you are creating it, since any time questions are asked or clarification is necessary, that might be a clue to add another detail.

Distribute and use your diagrams!

One of the most important things to do with your diagrams is to actually use them. Bring them to meetings, get them up on your project Wiki, and tape them to the wall! Having them out in the open will get them involved in discussions and allow team members to point at them during discussions. This will likely give you ideas for further modifications to improve or update your diagrams.