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.


Duplicate heading anchors in Confluence

There's a bug in Confluence 4.2 that generates identical IDs for same-name heading elements (CONF-17962). The issue is fixed in Confluence 4.3 but here is a workaround for those stuck with Confluence 4.2 or earlier.

Multiple same-name headings on the same page are OK. In fact, they are quite common. When I document objects that have similar properties I need to repeat headings. The problem in Confluence 4.2 is that you can't link to such headings (anchors). The link always points to the first occurrence of the heading.

Example: I use the following heading structure in message types documentation:
  • Banners
    • Behavior
    • Levels
    • Examples
    • Looks like
    • How to show
  • Alerts
    • Behavior
    • Levels
    • Examples
    • Looks like
    • How to show
  • Notifications
    • Behavior
    • Levels
    • Examples
    • Looks like
    • How to show

Confluence generates IDs using a pattern where page title and heading are concatenated with a hyphen in between:
<page title>-<heading name>

As a result, the IDs of all my "Behavior" headings are identical:
<h3 id="Messagestypes-Behavior">Behavior</h3>
<h3 id="Messagestypes-Behavior">Behavior</h3>
<h3 id="Messagestypes-Behavior">Behavior</h3>

Workaround. Add the Anchor macro in front of the lower level heading. Set the anchor name to the upper level heading followed by a hyphen.


This creates unique IDs:
<h3 id="Messagestypes-Banners-Behavior">Behavior</h3>
<h3 id="Messagestypes-Alerts-Behavior">Behavior</h3>
<h3 id="Messagestypes-Notifications-Behavior">Behavior</h3>


Keyboard shortcuts that look like keys

I spotted this CSS class being used in Chrome keyboard shortcut help. I applied the style to our keyboard shortcut documentation at Magnolia. Now the shortcuts look like actual keys. That was a quick way to add a bit of polish.
.kbd {
  background-color: #f7f7f7;
  border: 1px solid #ccc;
  color: #333;
  font-size: 13px;
  line-height: 1.4;
  text-shadow: 0 1px 0 #fff;
  font-family: Arial,Helvetica,sans-serif;
  display: inline-block;
  padding: 0.1em 0.6em;
  margin: 0 0.1em;
  white-space: nowrap;
  -webkit-box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset;
  -moz-box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset;
  box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset;
  -webkit-border-radius: 3px;
  -moz-border-radius: 3px;
  border-radius: 3px;
}

Here's the result: