Software Documentation Chapter 2: Writing to Teach

Study Notes

Writing to Teach - Tutorials

Introduction to Tutorials

Tutorials are often used to introduce new software to users, regardless of their level of expertise.
They follow principles of instruction that assume users progress in skill and confidence with a program.

Guidelines for Designing Tutorials

Identify skills to teach and break them down into specific tasks and program skills.
State objectives in measurable terms, focusing on real-world performance.
Choose the right type of tutorial based on the user's needs and goals.
Present skills in a logical, cumulative structure.
Offer highly specific instructions and practice exercises.
Provide feedback at each skill level.
Test the tutorial to ensure it is effective.

Types of Tutorials

Guided tour: presents an overview of program features, often with a low-interaction environment.
Demonstration: explains specific parts of a program, often with a limited version of the program.
Quick start: designed for experienced users, involves significant user interaction.
Guided exploration: contains instructions for users to try out commands, encouraging exploration.
Instruction manual: focuses on teaching users a number of complicated commands and functions.

Additional Considerations

Intention to teach: tutorials should aim to teach users skills and have them remember them for later tasks.
Selectivity in choosing material: focus on essential tasks and skills that need to be learned.
Stand-alone design: tutorials should be self-contained and able to teach users without additional support.

Designing Effective Tutorials

Know the user's needs and goals.
Use a storytelling approach to make the tutorial more engaging.
Use lots of examples and accurately design steps.
Focus on real tasks and activities.
Slash unnecessary verbiage and support active reading.
Encourage exploration and practice.
Support error recognition and recovery.

Comparing Approaches

Elaborative approach: good for users who like structure, traditional, and good for first-time users.
Minimalist approach: cuts writing time, less document length, and interesting, but may frustrate first-time users.

Additional Resources

BookStack: a simple, self-hosted platform for organizing and storing information.
How to make a tutorial video: includes tips on preparation, software, and post-production.

Description

This chapter focuses on writing tutorials for software, which can serve as a quick introduction to new software for users of all skill levels. It covers the principles of instruction and user progress.