The Write Stuff: Tutorial template in high-visibility format

July 14, 2017

rdgreen-July 14, 2017

Lab exercises and tutorials are a proven way to give staff and customers hands-on experience with a product. Good exercises offer the twin benefits of instilling customers with skills and confidence, as well as reducing the burden of support. This high-visibility template will help you create effective tutorials and other instruction-oriented materials.

(Source: Grey Flannel Graphics)

What is "high-visibility"?
High-visibility is the sense that a document's contents are "easy to see." Documents with high-visibility display the following characteristics:

  • Scan-able: Quickly gives the reader a feeling for the scope and scale of the topic.
  • Clear Organization: The organization is obvious and well-balanced. Hierarchy, fonts, numbering, etc., are used judiciously to present and manage detail.
  • Guides the Eye: Visual techniques such as shading, grouping, and callouts are used to focus the eye and make key elements "pop out."

Visibility has a large impact on the utility of a document, especially a technical one such as a manual. Visibility can be a subjective thing, however, so it's hard to provide any rigorous guide or outline. The eye is the ultimate judge, and the answer is to be found in a balance of elements. But I believe there is one useful clue: high-visibility contributes to a good first impression.

What makes this template special?
This tutorial document uses a high-visibility approach to organize the overall flow and make it easy to spot key information. In addition, there's a more ambitious goal: to create material that addresses the needs of both novices and experts with a single document.

How is this achieved? Often, experienced users will keep their own notes describing a flow or procedure. If you were to look at these notes, you would see the barest descriptions -- typically no more than a list of values or commands: Type the path '/usr/myCells.lib', enter '2.9', click 'Save'. Think of this as a form of cheat-sheet; it just holds "the answers."

By comparison, a novice user may need a full breakdown of the flow including detailed descriptions, illustrations, and screen shots. This template attempts to merge the two in a way that makes it easy to see what you want just by shifting your focus. This increases the "bandwidth" of the document, allowing it to meet the needs of the widest qualified audience.

Can I have a copy?
Sure. The template is provided in Word format (see the links below). First, I suggest you review the "Template Tour" presentation, which quickly lays out the strategy behind the design. In addition, take a look at the "Op Amp Tutorial" to see what a real tutorial looks like built with this template.

Is this easy to use?
That depends on your skill with Word. Microsoft Word is perhaps the most ubiquitous office automation program in the world and nearly all professionals have used it. However, the vast majority of people are self-trained with Word, and although most manage to get by, they (unknowingly) work with the tool at a rudimentary level. Very few folks are familiar with "Styles" (Microsoft's term for paragraph tags) or use features like tabs to achieve uniform alignment.

This template employs Styles to make it easy to control the formatting and achieve consistent results. (Styles is a substantial topic and deserves its own treatment; we will discuss this in more depth in a future column.)

One of the keys to this template is the use of tabs to achieve a particular effect with regard to alignment. The following illustration shows how right- and left-tabs are used to separate the "command-prompt" from the "user data" (the user-data represents "the answers"; i.e., the actual values or commands for which the user is responsible).

(Source: Ron Green)

At the end of the Template Tour is a brief introduction to Styles. I plan on following this up with a more thorough treatment of Word that should make it easier to create and manipulate Word docs and reduce much of the tedious manual formatting normally associated with Word.

If you need to create a lab or tutorial, please feel free to try out this template. Also, please let me know if you have any feedback for improvements or if you need a pointer or two.

Loading comments...