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?
Teachers, 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:
- Types of Materials
- Designing Step-by-Step Instructions
- Developing Step-by-Step Instructions
- Web-based, Print-based, or Both
- Explore How To's
- Learn More
Read Document to the Question by Bonni Graham to learn about why documentation is important and what type of manual might need to be written.
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:
Regardless of whether you're designing materials for individuals or groups, it's essential to consider the following elements:
- Quick-start: resources to help users who wish to get started quickly
- Demonstrations: examples of specific searches, features, typical use
- Samples: a wide variety of examples showing different uses such as topic options, subject area applications, and lesson ideas. Lists are very helpful such as sample questions, topic lists, or results.
- Practice: provide guidelines and ideas for practice projects
- Case Studies: stories of successes and inspiration for potential users
- Products: examples of things that have been produced using the hardware, software, or materials.
Professionally Produced Tutorials
- Adobe Studio: Photoshop, Illustrator, Go Live, In Design, Acrobat
- Macromedia: Dreamweaver, Fireworks, Flash, Freehand, Developer Center
- Microsoft Tutorials
Writing quality instructions require a knowledge of the hardware or software, as well as skills in writing.
Read 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.
- What's the reading level of the user?
- What is their experience with computers?
- What specifically do you want your learner to do with the software?
- How can you provide the most independent environment for your learner?
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.
- WetCanvas - step-by-step instructions for drawing
- Study Guides - online guides for study
- Fractals Lesson - online and handout for a Fractals lesson
- Module Three - online principles, procedures, and practice
- Microsoft Explorer Tutorials - web-based text and graphics
- FreeSkills - tutorials
Consider projects that incorporate both step-by-step use along with practice examples.
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.
The key to writing instructions is simplicity. Rather than paragraphs, use bullets, tables, and visuals.
Read 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:
- Use short, concise phrases or sentences.
- Use active, descriptive words.
- Be consistent in your use of words and type styles. Use bold, italic, and color for emphasis, yet don't over use these elements.
Explore examples of text-rich tutorials:
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).
Go 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:
- Atomic Learning: Mac OS X, Acrobat Reader, PowerPoint 2003, Dreamweaver 2004 - QuickTime videos
- Inspiration: Interactive Demonstration - Shockwave
- The Internet in Action - video and lesson plan
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.
- Inspiration: PowerPoint Slide Show
Some of the best How-Twos incorporate all of these options. Check out Mrs. Sterling's Word Pad page.
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).
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.
The following resources provide links of interest:
- Apple Publications Style Guide (2003) - specs for writing Apple documentation; great reference for writing software "how to's"
- EServer TC Library - good list of links to related resources
- Online Technical Writing
- Technical Writing by Nancy Halligan
- Quotes About Tech Writing - just for fun!
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