The Write Stuff: Tutorial template in high-visibility format -

The Write Stuff: Tutorial template in high-visibility format


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.

6 thoughts on “The Write Stuff: Tutorial template in high-visibility format

  1. “RonnnI have written many test documents for the products that we produce, and looking at your presentation I can see how woeful they are. They can certainly upgraded and this is providing much food for thought.nnI do have some other constraints though

    Log in to Reply
  2. “I use Word quite extensively, but I am sure there are still many features I still have to learn, so I look forward to your future blog. However I still find that whilst there are many great features, they don't always play well together- try getting autom

    Log in to Reply
  3. “Hi Aubrey. I can appreciate your sentiments regarding Word. If it's any consolation, you're in good company: over the years many people (far too many) have struggled to get Word to behave. This is unfortunate because in the largest of ways, Word is “the

    Log in to Reply
  4. “The concept of “High Visibility” is a great tool. It applies to more than just the documents we write. It is all about effectively communicating a concept to a target audience(s). A document well crafted is useful a a thing of beauty :-). Thanks for

    Log in to Reply
  5. “You're very welcome. I hope the template comes in handy. BTW, I revamped the presentation and turned it into a video. (I installed links in the comments above as well as on the front page of the Template Tour doc.)nInterestingly, engineers are happy to s

    Log in to Reply

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.