C. Designing Modular Programs · Modular and Object-Oriented Design

User Documentation: Help Files, Manuals and Training Materials

A4.4 A4.3About 70 minutes

Learning goals

I can explain the difference between internal (programmer) documentation and external (user) documentation.
I can plan a user manual around user tasks, with a quick start, how-to sections, troubleshooting and a glossary.
I can write clear, numbered, task-based instructions in plain language, with expected results.
I can build help into a program, including command-line help generated with argparse and an in-program help command.
I can keep user documentation maintainable by storing it with the code, versioning it and testing it with real users.

Words to know

external (user) documentation
Documentation for the people who use a program, rather than for the programmers who write it.

user manual
A complete guide to using a program, organized by the tasks users want to do.

quick-start guide
A short document that gets a new user through one complete task quickly.

help file / online help
Help built into or shipped with the program, such as a help command, a --help option or help pages.

training materials
Tutorials, exercises, slides or videos that teach users a program step by step.

README
A text or Markdown file at the top of a project explaining what it is, how to install it and how to start.

troubleshooting guide
A list of problems users may meet, with their likely causes and fixes.

changelog / release notes
A dated list of what changed in each version of a program.

usability test
Watching a real user try to complete tasks with the program and its documentation, to find where they get stuck.

The program is finished. Is it?

Your arena booking program works perfectly. Then the arena manager calls: "How do I book two teams back to back? What does 'booking must be within opening hours' mean? My volunteer says it crashed." A program that people cannot figure out how to use is not finished.

Last lesson was about internal documentation for programmers. Expectation A4.4 asks you to create clear and maintainable external user documentation, such as help files, training materials and user manuals. In industry, technical writers, developers and support staff all write it, and many software jobs expect you to contribute.

Know your reader

Before writing a word, decide who will read it and what they are trying to do:

A first-time user wants a quick start: one complete task, fast, with nothing extra.
A regular user wants to look up one task ("How do I cancel a booking?") and get straight to numbered steps.
A frustrated user has an error message and wants the fix.
An administrator wants installation, settings and backups.

Users do not care how your modules and classes are organized. Organize user documentation around their goals, not around your code.

A typical user manual structure. It is organized around what users want to do, not around how the code is organized.

Writing instructions that work

One action per numbered step, starting with a verb: "Type book, a space, then the team name."
Show the expected result after important steps ("The program replies Booked: Bantam A, 18:00 to 20:00"), so readers know they are on track.
Use exact names for everything on screen, written exactly as the program shows them, and use the same term every time (do not switch between "booking", "reservation" and "slot").
Plain language: short sentences, everyday words, define any technical term once in the glossary.
Examples beat descriptions: one real example command is worth a paragraph.
Warnings come before the step, not after: "Cancelling cannot be undone. Type cancel ...".
Accessible formatting: real headings, numbered lists, descriptive link text, alternative text for screenshots, and enough contrast. Many readers use screen readers or zoom.
Audience languages: many Canadian organizations publish their user documentation in both English and French, so write simply enough to translate well.

Worked example

Example 1: A how-to section and a troubleshooting table

Write the "How to book ice time" section of the arena program's user manual, and a troubleshooting table for the two most common problems. The command is book TEAM START END, hours are whole numbers on a 24-hour clock, and the arena is open from 6 to 23.

Title as a task: "How to book ice time". Users scan headings for their goal.
Before you start: "You need the team name and the start and end hours. Hours use the 24-hour clock: 18 means 6 p.m."
Step 1. Type book, the team name (use hyphens instead of spaces, for example Bantam-A), the start hour and the end hour, separated by spaces. Example: book Bantam-A 18 20.
Step 2. Press Enter. Result: the program shows Booked: Bantam-A, 18:00 to 20:00.
Step 3. To check, type list. Your booking appears in time order.
Troubleshooting, as symptom, cause, fix: (1) "booking must be within opening hours": the start is before 6, the end is after 23, or the end is not after the start; check the hours and try again. (2) "Bantam-A clashes with Figure-Club": another booking already uses part of that time; type list to see free times and choose another slot.
Note: the end hour is not included, so a booking that ends at 20 and one that starts at 20 do not clash. Say this once in the steps and once in the glossary ("end hour").

A complete how-to section has: a task title, what you need first, numbered one-action steps with an example, the expected result, and a link to troubleshooting. The troubleshooting entries quote the exact error message so users can match what they see.

Help built into the program

The best help is available where the user already is. Two common kinds:

Command-line help. Programs run from a terminal traditionally show a usage summary with -h or --help. Python's standard-library module argparse generates this text automatically from the arguments you define, so the help cannot fall out of date: change an argument and its help changes with it. This is a key idea for maintainable documentation: generate it from a single source where you can.
In-program help. Menu or command-based programs offer a help command, often with topics. Store the help text in one place (a dictionary or a file) rather than scattering print statements through the code.

Worked example

Example 2: Generated command-line help

Use argparse to define the arena program's command line: a team name, a start hour, an end hour and an optional --dry-run flag. Show the values it reads from a sample command line, and the help text it generates.

ArgumentParser(prog=..., description=..., epilog=...) sets the program name, a one-line description shown at the top, and an example shown at the bottom.
Each add_argument gives the argument's name, its type (type=int converts the text to a number and reports an error if it is not one) and a help string written for users.
action="store_true" makes --dry-run a flag: present means True. On the command line, the dash in the name becomes an underscore in the program: args.dry_run.
In a real program, parser.parse_args() with no list reads what the user typed, and arena --help prints the help and exits. Here a sample list is passed so the example can run anywhere.
parser.print_help() prints the same text a user would get from --help.

Code and output below. The exact line wrapping depends on the window width, and Python versions before 3.10 print "optional arguments:" instead of "options:".

import argparse

parser = argparse.ArgumentParser(

prog="arena",

description="Book ice time at the community arena.",

epilog='Example: arena "Bantam A" 18 20')

parser.add_argument("team", help="name of the team or group")

parser.add_argument("start", type=int, help="start hour, 6 to 22 (24-hour clock)")

parser.add_argument("end", type=int, help="end hour, 7 to 23 (not included)")

parser.add_argument("--dry-run", action="store_true",

help="check the booking without saving it")

# A real program would call parser.parse_args() to read the command line.

# Here we pass a sample command line so the example runs anywhere.

args = parser.parse_args(["Bantam A", "18", "20", "--dry-run"])

print(args.team, args.start, args.end, args.dry_run)

print()

parser.print_help()

arena_cli.py: the help text is generated from the argument definitions.

Bantam A 18 20 True

usage: arena [-h] [--dry-run] team start end

Book ice time at the community arena.

positional arguments:

team name of the team or group

start start hour, 6 to 22 (24-hour clock)

end end hour, 7 to 23 (not included)

options:

-h, --help show this help message and exit

--dry-run check the booking without saving it

Example: arena "Bantam A" 18 20

Output of the program above (what Python prints).

HELP_TOPICS = {

"book": "To book ice time, type: book TEAM START END\n"

"Example: book Bantam-A 18 20 (6 p.m. to 8 p.m.)",

"cancel": "To cancel, type: cancel TEAM START\n"

"Example: cancel Bantam-A 18",

"hours": "The arena is open from 6 (6 a.m.) to 23 (11 p.m.).",

}

def show_help(topic=""):

"""Print help for one topic, or the list of topics."""

topic = topic.strip().lower()

if topic in HELP_TOPICS:

print(HELP_TOPICS[topic])

else:

if topic:

print(f"No help for '{topic}'.")

print("Help topics:", ", ".join(sorted(HELP_TOPICS)))

print("Type: help TOPIC (for example: help book)")

show_help("book")

show_help("refund")

help.py: in-program help topics stored in one dictionary. Unknown topics get a helpful list instead of an error.

To book ice time, type: book TEAM START END

Example: book Bantam-A 18 20 (6 p.m. to 8 p.m.)

No help for 'refund'.

Help topics: book, cancel, hours

Type: help TOPIC (for example: help book)

Output of the program above (what Python prints).

Training materials

A manual answers questions; training materials teach. They include tutorials, practice exercises with answers, slide decks, short videos and cheat sheets. Good training material:

states the goal of each session ("By the end, you can book and cancel ice time.");
uses a realistic scenario ("The Bantam A coach needs Saturday 7 to 9 a.m.");
moves from simple to complex, one new idea at a time;
gives learners a task to try and the expected result to check against;
ends with a one-page quick reference of the most common commands.

This is the same structure as the lessons on this site, for good reason.

Keeping user documentation maintainable

User documentation goes out of date the moment the program changes, unless you plan for it:

Store docs with the code. Many projects keep a README.md at the top and a docs folder written in Markdown, a plain-text format that any editor can open and version control can track. (The Software Development: Managing a Team Software Project unit covers version control.)
Update docs in the same change as the code. A feature is not done until its documentation is.
Generate what you can from one source: argparse help, docstrings, a help dictionary.
Version the documentation to match the program, and keep a changelog listing what changed in each release.
Test documentation with real users. Watch someone follow the quick start without help. Every place they hesitate is a place to fix.

Maintainable documentation lives with the code (often as Markdown files in the same project) and is updated in the same change, so every release ships with documentation that matches it.

A README template

A good README answers, in order: What is this? (one sentence) Why would I use it? How do I install or start it? (exact commands) How do I do the main task? (a short example with expected output) Where can I get help or report a problem? What licence is it under, and who made it? Many people decide in under a minute whether to use a project, based only on its README.

Just for fun

Technical writers have an old saying: "When all else fails, read the instructions." Your job is to write instructions good enough that people read them before all else fails.

Hands-on activity

The usability test

You need: a program you wrote (from this unit or earlier), a computer with Python, paper, and one family member who has not seen the program.

Write a quick-start guide for your program: at most one page, one complete task, numbered steps, expected results.
Add a help command or a --help option to the program.
Give your tester the guide and the computer. Ask them to complete the task without asking you anything. Ask them to think aloud as they go.
Sit behind them and say nothing. Write down every place they hesitate, misread a step, or type something unexpected.
Afterwards, fix the guide (and, if needed, the program's messages). If possible, test again with someone else.
Add a short troubleshooting table covering what went wrong, in symptom, cause, fix form.

What to look for: the tester finishes the task; every step has one action; the guide uses the program's exact words; at least one improvement came directly from watching the test.

Your turn

What is the difference between internal and external documentation?

Rewrite this step so it follows the guidelines: "Then you should probably go ahead and enter the info about the booking and stuff into the system."

Name four sections of a typical user manual.

Why should a troubleshooting table quote the program's exact error message?

In Example 2, what does type=int do for the start argument?

Using Example 2's help.py, what does show_help(" Hours ") print?

Give two ways to keep user documentation from going out of date.

More practice: warm-up

Which command-line option traditionally shows a program's help?

What standard-library module generates --help text in Python?

What file usually sits at the top of a project and explains what it is?

What is a changelog?

Who is a quick-start guide written for?

More practice: on your own

Write a three-row troubleshooting table (symptom, cause, fix) for a program that reads marks from a file called marks.txt.

Add an argument to Example 2's parser: an optional --coach with a default of "unknown", shown in help as "the coach's name". Write the line.

Add a "list" topic to HELP_TOPICS explaining that list shows all bookings in time order. What does show_help("") now print as its topic list?

Outline a 20-minute training session that teaches arena volunteers to book and cancel ice time.

A user manual has screenshots of the program. Why might they make the manual harder to maintain, and what can help?

Challenge

argparse can check values itself with choices. Change the start argument so only hours 6 to 22 are accepted, and explain why this is better documentation as well as better validation.

Design the documentation set for the ski rental program from this unit, for three audiences: counter staff, the shop owner, and a future programmer. Say which documents each gets.

Some developers say "If it needs a manual, the design is wrong." Give one way this is true and one way it is not.

Check your understanding

Quiz

Which is external (user) documentation?

How should a user manual be organized?

Which is the best instruction step?

Why is argparse-generated --help considered maintainable?

What is the main purpose of a usability test of documentation?

Where should user documentation for a software project usually be kept?

For parents and teachers

Big idea: A4.4 asks students to create clear and maintainable external user documentation, such as help files, training materials and user manuals. This lesson covers planning by audience and task, writing clear instructions, built-in help (including Python's argparse), training materials and keeping documentation up to date. The Software Development: Managing a Team Software Project unit applies these skills to a full project.

How to help: You are the ideal usability tester, especially if you are not a programmer. Follow your teen's quick-start guide exactly as written, think aloud, and do not ask for hints. Every hesitation is useful feedback.

Common difficulties:

Writing for programmers (talking about functions and classes) instead of users.
Steps that combine several actions or leave out the expected result.
Using different words for the same thing.
Treating documentation as an afterthought, so it no longer matches the program.