10 Principles for a Great Technical Tutorial
I’ve compiled these 10 Principles for a Great Technical Tutorial on the basis of my experience as a technical writer who worked for Fortune 100 companies for over 20 years.
As a technical writer you may be asked to write and design on-line tutorials on topics ranging from how to set up a customer service center or how to configure a radar system, to how to clean a commercial kitchen. The list of businesses that need a good on-line tutorial is endless.
Here are 10 ways to instantly improve the quality of your tutorials:
1] Make sure your tutorial is organized in sequential logical steps. Don’t confuse the steps. And make sure your main topics are divided into easy to digest related sub-topics.
For example, if your main topic is to install a software, make sure one of the related sub-topics is the prerequisite hardware needed to run the software.
2] Make sure you have clear, unambiguous and consistent navigation to move between the topics back and forth. Navigation should be in the same place and should use the same buttons for each topic screen.
3] Do not drill down too much into indented layers. Make sure every screen is accessible with a maximum of two (2) clicks.
4] Make sure you have a HOME button on every screen to quickly return to the main screen.
5] An Index is not easy to prepare but very useful. Users always appreciate an Index. Use nouns and stay away from verbs as your index entries. For example, don’t use “Changing battery” as an index entry. Instead make ” Battery” the first-level entry, and follow it with “changing” as an indented second-level entry.
6] Make sure your on-line tutorial works with all the major browsers and does not require any fancy or expensive plug-ins.
7] Some people turn off images and/or Javascript for faster viewing. Make sure that your tutorial works and makes sense even without any images or Javascript.
8] Do not use unnecessary graphics. All images should be relevant to the subject be right next to the text that it helps explain.
9] If you are using any sound clips, videos and animations, make sure they are in the most-widely used format (like MP3 or Flash).
10] It always helps to have each topic fit into an average 17″ screen to eliminate the need for vertical or (even worse!) horizontal scrolling.
