May 5, 2014

Write the Docs: Geoffrey Grosenbach – Graphical Explanations

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Geoffrey is the VP of Open Source Content at Pluralsight, a video tutorial company. He opened his talk speaking about Information Anxiety and how the book was written for someone to skim, flip, or read through. Each is a valid means for consuming information. Could we apply this approach to documentation?

Graphical elements allow your documentation to be consumed at different rates and in different flows. It can be more respective of your reader’s time. As part of this Geoffrey recommended reading Information Dashboard Design, which looks like a fascinating book.

One way that he’s used graphical explanations is through type. Yes, it’s text but there is plenty we can learn just from type. When the web started it was designed as a textual delivery system; graphical requirements weren’t necessarily considered. Many of our documentation systems still take this approach. A simple pull quote can be a graphical hook that lets someone skimming a document understand the core ideas. Combinations of font size and color also convey graphical meaning. Think of a stop sign or a warning sign as two main examples.

Icons are the next graphical explanation Geoffrey covered. One of his favorites is Symbolicons, an icon font that looks like a neat tool for easily adding vector icons to your text.

Beyond that the power of graphics is not just that we’re making pictures on the screen. The power lies in the explanation behind that graphic and its ability to communicate the meaning within a document.

There are models for conceptualizing these explanations. Geoffrey walked us through examples of good/bad, good/better/best, before/after, and other core comparisons we understand as explanations. Many involve showing a reader the different types side by side. It helps understand how something can be transformed or what an ideal result is.