Documenting design guidelines

We just published the first batch of app design guidelines for Magnolia CMS. Here is what I learned about documenting UI design.

Few people like to read long design theory. We thought about how to get the message across and chose a radically different approach. Each design guideline is a short recipe card that is highly focused and visual. One card is one solution. A deck of cards is a better user experience.

Card anatomy:
  • Title tells you what to do. The imperative verb is familiar from recipes: Be a good tablet citizen
  • Tweet motivates the reader and lets me promote the guideline.
  • The "Why" explains why this topic is important. There has to be a reason for the card. 
  • Concrete examples relate to real-world usability issues.
  • Visual interest makes the card a delight to read. Screenshots are crucial.

I organized the card text like a news story. This style is known as inverted pyramid. Important information is at the top. Details follow in order of diminishing importance towards the bottom.

The pyramid format works great for two reasons:
  1. Developers can leave the card at any point and still understand it.
  2. For those developers who wish to proceed, the pyramid gives more details.
The inverted pyramid is an unusual choice in technical documentation. Tech docs are typically comprehensive – all features are given equal importance. Everything has to be covered because you don't know what the reader is looking for.

However, design guidelines are more like persuasive text. Strictly speaking, you don't need to read them. You can build a perfectly functional Magnolia app without reading a single guideline. With the card format I try to persuade developers to adopt a few sound design principles to make apps better. The inverted pyramid information structure has the best chance of getting at least the key message across.