Teacher Tap

 

Technical Writing: How To's, Tutorials, and Directions

We need a set of instructions for some of our equipment. How do you write quality, step-by-step instructions?

What's the best way to lay out a page for step-by-step instructions?

Should I create web-based or print-based instructions?

writingTeachers, librarians, and technology coordinators are often faced with the need to explain a procedure or teach someone how to use a piece of software. This type of instruction takes a number of specific skills including technical writing. In some cases, users will be reading documents or using self-instructional materials. In other cases, you may be creating materials such as scripts and presentations that can be used in instructor-lead workshops and courses.

On this page, explore the following topics:

eye means readRead Document to the Question by Bonni Graham to learn about why documentation is important and what type of manual might need to be written.

Types of Materials

Self-Instructional Materials

People tend to use documentation in three ways. First, to get started. Some people don't know how to "open it", "install it", or "play the game." You need documentation to help users begin using the materials. Second, you need help when you have a specific question that can't be answered through experimentation. Third, you need help in applying the skills to new activities and projects.

What kind of "how to" resources do you need?

Group Instructional Materials

In some cases, you may be designing presentations for small or large groups. In this case, you may develop large group presentations to use in addition to tutorials. Some people like to use scripts for these types of training sessions. These scripts may be created in a word processing document or in the Speaker Note area of PowerPoint.

Explore examples of workshop scripts:

Essential Materials

Regardless of whether you're designing materials for individuals or groups, it's essential to consider the following elements:

Professionally Produced Tutorials



Designing Step-by-Step Instructions

Writing quality instructions require a knowledge of the hardware or software, as well as skills in writing.

eye means readRead my article Writing How To's (PDF document) file to learn more about writing step-by-step instructions.

Regardless of whether you're working with children or adults, there are many things to consider when writing step-by-step instruction.

Explore and evaluate some "how to" documents found on the Internet. For example, examine Tammy's Instructions Page. Look for strengths and weaknesses. Create a list of guidelines for writing instruction sheets and online tutorials. The links below contain "non-technology" how-tos to explore.

Consider projects that incorporate both step-by-step use along with practice examples.



Developing Step-by-Step Instructions

You'll find that some tutorials use many visuals, while others use primarily text. Be sure to consider the wide variety of learners who will use your tutorial. Some people learn more effectively through text and others through videos or audios.

Text Instructions

The key to writing instructions is simplicity. Rather than paragraphs, use bullets, tables, and visuals.

eye means readRead Alternative to the Paragraph by Jean Weber in Journal of the Australian Society for Technical Communication (NSW) Inc. (August 1989, pp. 14-16.)

Read Be Concise from Good Documents. Then, select from their other short articles on writing techniques.

When writing directions, consider the reading level of your end user. Consider the following guidelines:

Explore examples of text-rich tutorials:

Visuals

Visuals are an important part of any set of instructions. Diagrams are a good idea for demonstrating the relationships and events in the software. Photographs are good for equipment "how tos".

Consider using screen shots in your handouts (see Downloading Files Step-by-Step for an example).

eye means readGo to Screen Grabber from Teacher Tap.
Learn to use capture screens for use in your project.

Use visuals as a quick way to identify tools in a program. An important resource is a quick reference to using the basic tools of a program. Explore some examples of quick references:

Explore examples of visually-rich tutorials:

Regardless of whether you're using screen captures or photographs, you'll probably need to resize your graphics. You don't need any special software. Microsoft PAINT comes with most versions of Windows. Look in the Programs area of Windows, choose Accessories area to see what programs might be available.

Use the Microsoft Paint program for resizing. Open an image. Choose Image and Attributes to change the height and width. In this program you'll need to do some math to be sure that change the height and width proportionally so the image doesn't look scrunched. Most programs such as Adobe Photoshop and Macromedia Fireworks automatically do proportional resizing.

Think of 100 pixels as about 1 inch. this is a little off (it's 72 dpi=1 inch), but it goes you a feel. So you want things that are 200 to 300 pixels high and wide for must documents or web pages. Small icons might be 30x30 pixels.

If you see something called resolution, you want 72 dots per inch. no more for screen viewing. Some photos are as much as 300 dpi, which slows down loading. However if you plan to print your document, leave the graphics at the higher dpi for the print version of your handout.

Videos and Animations

Increasingly tutorial developers are using PowerPoint, videos, and Flash animation to create tutorials. These don't need to be completed. For example, check out the animated gif used in this Inspiration: Adding Ideas with Rapid Fire example.

Explore examples of motion-rich tutorials:

PowerPoint is a popular tool because it can be used for both large group and small group applications. If it is intended to be used by large groups, the images and text must be large. If it's intended to be used by individuals, it must have detailed, clear explanations.

Some of the best How-Twos incorporate all of these options. Check out Mrs. Sterling's Word Pad page.

Web-based, Print-based, or Both

What's the most effective way to provide directions for teachers and students; web-based, print-based, or both? In most cases, it's best to provide many different options. Some people like to read off the screen, while others prefer printed directions.

The advantage of web-based instruction is that the developer can incorporate interactive aspects such as links to other websites, practice activities, and color. If you place the instructions on the Internet, people everywhere can benefit.

Many people prefer reading from paper. They can take notes on the document and file it for later use. In addition, they can learn an application without switching between the tutorial page and the application screen. If you want people to print directions from the web, it's best to include a PDF file for people to download rather than asking people to print off the screen.

Learn more about Adobe Acrobat and how to create PDF files at Acrobat from Teacher Tap. You can also create an easy-to-print format. Check out the Land Grants project for an example.

Explore the many tutorial resources at the Technology Tutorials for Teachers page. You'll find "how tos" that are screen-based, as well as those intended to be printed.

If you're planning to use Microsoft Word for creating a print document, you can convert this document to a PDF file and a HTML web page. To learn this process, read Building Web pages with Microsoft Word from Teacher Tap (Word version or PDF version).

If you're planning to use Microsoft PowerPoint and need some help, use the links at PowerPoint Resources from Teacher Tap (Word version).

Explore How To's

Why reinvent the wheel? Before writing a set of instructions, explore the online resources already available.

First, look for resources you could use. You could bookmark the website, add a link to your web page, or print the resources.

Second, seek out materials that could be adapted to meet your needs. For example, you might find directions for an older version of software. Use their ideas and examples as a starting point for your project.

Third, you may find that no online materials are available. This is your chance to add to the wealth of online resources.

 

Learn More

The following resources provide links of interest:

Technical Writing

 

Try Some Technical Writing

Choose one of the following two activities:

Option 1: Critique the documentation that comes with a piece of children's software. Is the documentation written for children or adults? Are there visuals to assist the learner in using the software? Are they helpful? Are there troubleshooting tips that would be helpful if the user runs into trouble? Provide a list of strengths and weaknesses, then develop a list of recommendations that could be sent to the publisher.

Option 2: Select a piece of children's software that contains poor documentation. Develop a simple, one page set of instructions that students could use to get started with the software. Or, write some documentation for a utility in the lab such as the new printers, Capture, or Fetch


| eduscapes | IUPUI Online Courses | 42explore | escrapbooking | About Us | Contact Us | © 2000, 2007 Larry Johnson & Annette Lamb