Quick Reference Guides: Short and Sweet Documentation – Tom Johnson…

THANX!!!

Another use I have found for the “reference guide” format is in sales, specifically large “technical solution sales”.

Tender documents, proposals and associated clarifications can add up to a sizable stack of paper. A severe case of the “almighty thud” syndrome, worse still for the poor client faced with many vendors.

I’ve used the reference guide technique a few times to try to cut through the noise, and each has been a phenomenal success. I’ve produced a laminated reference card to be distributed and used at the formal presentation stage.

The best example was for a multi-million deal to build market monitoring systems for a regulator. Our reference card in that case was double-sided A4, and we devoted half the space to just describing the problem and the domain. After winning the deal, I heard informally that our graphical representation of the market model and all its complexities had totally won them over. The client had even been using the chart internally as a reference to guide their own discussions.

I use the technique sparingly, since they can take a lot of work to produce and simply get your story down to that 1 or 2 pages in a way that is still meaningful and substantive. And not every situation is appropriate: I think best where the problem domain or the solutions are unavoidably complex, and you know the complexity is muddying the water for all involved.

But when you do it right, it can be a very powerful tool.

For example, think of USA Today. We all know what the blue, green, purple, and red colors represent. This becomes important as you create a series of job aids for a particular project.

Another great example is over at http://quamut.com/ They’ve got great layouts and use color to represent different categories. I encourage you to print out a couple of their free examples.

Another great post, Tom. Thanks.

* Analyze the organization (information design) of the topics you want to present as one-pagers. Notice whether the topics’ pieces can be presented effectively using the same layout.

* Use text attributes, shading, and color as features to visually tag the different kinds of information on the page, to give the reader visual hints about what is being presented in each panel. If you must create variant layouts for some topics, re-use those features across varying layouts.

* If there will be more than one such one-pager, decide whether they will refer to each other and how, and how each refers to the main body of the product’s documentation.

* A design-intensive one-pager can be a challenge to read online if the reader’s screen is not properly sized. Layouts that emphasize left-right visual relationships might fare better than above-below visual relationships. The latter is a usability issue for many web pages, where the reader must constantly scroll up/down to make sense of what is being presented.