Graphical Explanations

Authors:Geoffrey Grosenbach Time:14:10 - 14:30 Session:http://docs.writethedocs.org/2014/na/talks/#geoffrey-grosenbach-graphical-explanations Link:

Formerly ran PeepCode, now at PluralSight.

In the late 1980’s, the founder of the TED Conferences wrote a book, Inforation Anxiety, about how just getting access to information wasn’t enough. People would be willing to pay for curation and filtering. And he actually wrote the book in such a way that you could read it at different levels: you could read the TOC and get something, flip through it and get something more, or really read it and gain deep knowledge.

Can we apply that to documentation? Give people the ability to skim for a graphical representation if they don’t have time to read it all, or really dive deep if they have time.

What are some easy ways to do this?

1. Type

   It’s the way we communicate, and it’s everywhere, so learn to use it well.

2. Color

   (pygments is a great way to handle this formatting, depending on your tool chain.)

3. Icons

   SymbolSet / Symbolicons

4. Explanatory tools

   • Before/After
   • Video
   • Icons to indicate “warnings” or “best paths”
   • Good/Better/Best