Grade by Grade
B. Software Development · Software Development: Managing a Team Software Project

User Documentation, Training Materials and Deployment

A4.4 B1.3About 75 minutes
Learning goals
  • I can choose the right kinds of external documentation (user guide, help, quick reference, README, installation guide, release notes, training materials) for each audience.
  • I can write clear, task-based user instructions with numbered steps, examples and troubleshooting.
  • I can keep documentation maintainable by storing it with the code and generating help from a single source.
  • I can plan and deliver a short training session with hands-on practice.
  • I can package and deploy a release with semantic version numbers, release notes and an installation checklist.

Words to know

external (user) documentation
Documents for the people who use, install or support the software, as opposed to internal documentation (comments and docstrings) for programmers.
user guide (manual)
A task-based document explaining how to do each job with the software, with steps, examples and troubleshooting.
help file / in-program help
Short explanations available from inside the program, usually for one screen or option at a time.
quick reference card
A one-page summary of the most common tasks, designed to sit beside the computer.
README
A short text file at the top of a project explaining what it is, how to install and run it, and where to find more help.
release notes (changelog)
A list of what changed in each version: new features, fixes and known problems.
semantic versioning
Version numbers MAJOR.MINOR.PATCH: increase PATCH for bug fixes, MINOR for compatible new features, MAJOR for changes that break compatibility.
deployment
Installing and setting up the software in the place where it will really be used, so that users can start using it.

Software nobody can use is not finished

LendIt works. Every test passes. But on the first Saturday a volunteer who has never seen it stands at the front desk with a line of families holding snowshoes. If she cannot figure out how to record a loan in under a minute, the binder comes back out, and six weeks of work sit unused.

The curriculum asks you to create clear and maintainable external user documentation (e.g., Help files, training materials, user manuals) (A4.4) and, as part of producing the software, to create user documentation and training materials (B1.3). Then the software has to be deployed: packaged, installed and handed over in a form the client can actually use. (Internal documentation, such as docstrings and comments for programmers, was taught in the lesson Code Maintenance: Documenting Code to Industry Standards in the unit Data Types, Files and Expressions; this lesson is about documents for everyone else.)

Different readers need different documents

Start by asking who will read each document and what they are trying to do at that moment:

  • Users (front-desk volunteers) want to finish a task now: "How do I return an item?" They need a quick reference card, in-program help, and a task-based user guide.
  • Trainers (Denise) need to teach new volunteers: a training plan, practice exercises with sample data, and the user guide.
  • Installers and support people (the centre's IT volunteer) need a README, an installation guide, and release notes saying what changed in each version.

Write one document per purpose. A single giant manual that tries to serve everyone serves no one.

Volunteersquick reference cardin-program helpuser guide (tasks)Denise (trainer)training planpractice exercisesuser guideIT volunteerREADMEinstallation guiderelease notesFuture developersREADMEdesign documentdocstrings, commentsExternal user documentation (A4.4) serves the first three groups;internal documentation is in Data Types, Files and Expressions.
Each audience gets the documents that fit its task. The quick reference card and in-program help are read most often, so they must be the clearest.

Writing a user guide that works

Good user documentation is task-based: organized by what users want to do (lend, return, find overdue items), not by how the program is built (main.py, loans.py).

  • One section per task, with a heading that names it: "Returning an item".
  • Numbered steps, one action each, in the order the user does them.
  • Show exactly what to type and what the screen will show, with real-looking examples.
  • A troubleshooting part that quotes every error message the user might see and says what to do.
  • Plain language and short sentences. Define any term the user does not already know.
  • Accessible formatting: real headings, enough contrast, large enough text, and a text description for every screenshot so a screen reader can describe it. Consider the languages your users speak; at Maple Grove, a French version is planned for a later release (N5).

Always test the documentation the way you test code: give it to someone who has never used the program and watch where they get stuck.

Model: one section of LendIt's user guide

LendIt User Guide, version 1.0 · Section 3: Returning an item

When to use this: a member brings back something they borrowed.

  1. At the main menu, type 2 and press Enter.
  2. Type the item ID from the white label (for example SK-07) and press Enter. Upper or lower case both work.
  3. LendIt shows the item, the member and the due date.
  4. If the item is late, LendIt shows the fee, for example 3 days late: fee $0.75. Collect the fee and press Enter.
  5. Put the item back on its shelf.

If something goes wrong:

  • "SK-07 is not on loan": the item was already returned, or the ID was mistyped. Check the label.
  • "No item SK-70": check the digits; IDs are two letters, a hyphen and two digits.

Rule to remember: the fee is $0.25 a day and never more than $5.00. Items returned on the due date are not late.

Worked example

Example 1: Improving a help screen

Luc's first draft of the Lend help says: "Enter the item_id and member_no. The function computes due_date using LOAN_DAYS and appends to loans." Rewrite it for a volunteer.

  1. Remove programmer words (item_id, function, LOAN_DAYS, appends). The volunteer does not need to know how it works.
  2. Say what to do, in order: "Type the item ID from the label (like SS-01) and press Enter. Then type the member's 4-digit number and press Enter."
  3. Say what happens and what to do next: "LendIt shows the due date, two weeks from today. Tell the member."
  4. Cover the common problem: "If LendIt says the member already has 3 items, they must return one first."
  5. Test it: Amara's younger brother, who has never seen LendIt, follows it successfully in 40 seconds.

"Type the item ID from the label (like SS-01) and press Enter. Type the member's 4-digit number and press Enter. LendIt shows the due date, two weeks from today: tell the member. If LendIt says the member already has 3 items, they must return one first."

Making documentation maintainable

Documentation goes out of date the moment someone changes the program and forgets the manual. Three habits keep it maintainable:

  1. Keep docs with the code in the repository (as Markdown files in docs/), so that a change to a feature and its documentation can be in the same commit and the same pull request, and reviewers can check both.
  2. Single source: write a piece of information once and generate the other forms from it. LendIt keeps its help text in one dictionary; the program displays it, and the same dictionary produces the help page for the user guide.
  3. Version the documents with the software: "User Guide, version 1.0" matches LendIt 1.0.0. Release notes list what changed.
HELP = {
"1": ("Lend an item", "Type the item ID (like SS-01), then the member number. "
"Tell the member the due date shown."),
"2": ("Return an item", "Type the item ID. If a fee appears, collect it."),
"3": ("Show overdue items", "Lists items past their due date with member and days late."),
}
def show_help(choice):
"""Print help for one menu choice (used inside LendIt)."""
title, text = HELP.get(choice, ("Unknown option", "Choose a number from the menu."))
print(f"{choice}. {title}: {text}")
def help_page():
"""Return the same help as a Markdown page for the user guide."""
lines = ["# LendIt help", ""]
for key in sorted(HELP):
title, text = HELP[key]
lines += [f"## {key}. {title}", text, ""]
return "\n".join(lines)
show_help("2")
show_help("9")
print(help_page())

Output: the help for option 2, the friendly message for an unknown option 9, and then a Markdown help page with a heading and paragraph for each option, generated from the same dictionary. Change the text in one place and both the program and the page change.

Training materials

Requirement N3 says a new volunteer must be able to use LendIt after 15 minutes of training. Luc writes a training plan and materials:

  • Objectives: by the end, a volunteer can lend an item, return an item (with a fee), and find the overdue list.
  • Demonstration (4 minutes): Luc shows each task once, saying what he is doing.
  • Guided practice (8 minutes): the volunteer does each task with a practice data file (made-up members and items, never real data), following the quick reference card.
  • Check (3 minutes): the volunteer does a short scenario alone: "Member 2001 returns SK-07, 3 days late." Luc watches but does not help.
  • Leave-behind: the laminated quick reference card and the user guide.

The training session is also a test: if volunteers struggle at the same step, the program or the documents need fixing.

LendIt 1.0: quick referenceLend1 → item ID → member no. → tell the due dateReturn2 → item ID → collect any fee shownOverdue3 → phone the members listedHelp6 → the option number you needQuit7 (saves everything first)Stuck? Item IDs are on the white label, e.g. SS-01. Call Denise: ext. 214
LendIt's quick reference card, printed and kept beside the laptop. It covers the five things volunteers do most, in the order of the menu.

Deployment: getting it into the client's hands

Deployment turns the code in your repository into a working installation at the client's site. For LendIt:

  1. Version it. Tag the release in Git (for example, git tag v1.0.0). Use semantic versioning: MAJOR.MINOR.PATCH.
  2. Package it: a folder LendIt-1.0.0 containing the program files, an empty data folder, the README, the user guide and the quick reference card. No tests, no .git, no __pycache__, and never the team's test data.
  3. Write the release notes: version, date, what it does, known issues (the help typo, if not yet fixed), and how to report problems.
  4. Install on the real computer using the installation checklist: check the Python version (N1), copy the folder, create a desktop shortcut, run the program, record one test loan and delete it.
  5. Set up data safely: enter the real items, back up the data folder daily (risk K3), and keep the paper binder for one week as a fallback.
  6. Train the users and hand over the documents.
1.MAJORchanges that breakold files or habits2.MINORnew features thatkeep old things working3PATCHbug fixes only,nothing newLendIt 1.0.0 → 1.0.1 (help typo fixed) → 1.1.0 (skate sizes added) → 2.0.0 (new file format)
Semantic versioning. A version number tells users at a glance whether an update only fixes bugs, adds features, or needs care because it changes something they rely on.

Version numbers are not decimals: 1.10.0 is later than 1.9.2. Comparing them as text gets this wrong, because text comparison looks at characters one at a time and "1" < "9". Convert each part to a number first:

def parse(version):
"""Turn "1.10.0" into the tuple (1, 10, 0) so versions compare as numbers."""
return tuple(int(part) for part in version.split("."))
print("1.10.0" > "1.9.2") # compares text, character by character
print(parse("1.10.0") > parse("1.9.2")) # compares numbers
print(sorted(["1.10.0", "1.9.2", "1.2.0"], key=parse))

Output: False / True / ['1.2.0', '1.9.2', '1.10.0'] (one line each)

Worked example

Example 2: Release notes for LendIt 1.0.1

Two weeks after delivery, the team fixes a help-screen typo that a volunteer spotted and a bug where searching for an empty string listed every item. They also improve the wording of one error message. What version number should the release get, and what do its release notes say?

  1. All three changes are fixes: no new features, nothing that breaks existing data. So it is a PATCH release: 1.0.0 becomes 1.0.1.
  2. LendIt 1.0.1 · Friday, December 18, 2026.
  3. Fixed: help for option 6 said "press 8"; it now says "press 7". Searching with an empty search no longer lists every item; it asks for at least one letter. The message for an unknown item ID now shows the expected format (two letters, a hyphen, two digits).
  4. Upgrade: close LendIt, replace the program files in the LendIt folder, keep the data folder. No change to data files.
  5. Known issues: none.

Version 1.0.1, with short release notes under the headings Fixed, Upgrade and Known issues.

Just for fun

The word manual comes from the Latin manus, "hand": a manual is literally a handbook. Which explains why most people only reach for one once something is already in their hands and not working.

Hands-on activity

Project step 12: Document, train and deploy

You need: your finished (or nearly finished) project, a helper who has never used it, and a timer.

  1. Audiences: list who will use, install and support your program, and decide which documents each needs.
  2. Write a user guide with one section per main task (numbered steps, examples, troubleshooting that quotes your real error messages). Save it as docs/user-guide.md.
  3. Write a quick reference card that fits on one page and a README (what it is, how to install and run it, where the guide is).
  4. Put your in-program help in one place (like the HELP dictionary) and, if you can, generate a help page from it.
  5. Test the docs: give the quick reference card to your helper and time them doing two tasks. Fix every place they got stuck.
  6. Write a 15-minute training plan with practice data and deliver it to your client.
  7. Deploy: tag the release (git tag v1.0.0), make a clean package folder, write release notes, and install it on the computer your client will use, following a checklist.

What to look for: task-based headings; no programmer words in user documents; every error message explained; documents and program have the same version number; the install was tested on the client's computer.

Your turn

1

Name four kinds of external user documentation.

2

Why should a user guide be organized by task rather than by module?

3

Rewrite for a volunteer: "Invoke option 3 to enumerate loans where due < today."

4

What does "single source" mean for documentation, and why does it help?

5

A release adds the skate-size feature and keeps old data files working. The current version is 1.0.1. What is the new version?

6

What does print("2.0.0" > "10.0.0") print, and why is it misleading?

7

Why must training use practice data instead of the centre's real member list?

More practice: warm-up

1

What is a README?

2

What are the three parts of a semantic version number?

3

What goes in a troubleshooting section?

4

Which document sits beside the computer and fits on one page?

5

Name one thing that should never go into the client's release package.

More practice: on your own

1

Write the troubleshooting entry for the message "Member 1042 already has 3 items out."

2

Using the help program, what does show_help("3") print?

3

The team adds option 4 (Add a new item) to the menu but forgets the help text. What does show_help("4") print, and how should the process catch this?

4

Give three steps of an installation checklist for LendIt.

5

Explain how the 15-minute training session is also a test.

Challenge

1

Extend help_page so that it starts with a table of contents listing each option on its own line, like - 1. Lend an item, before the sections. Describe the change.

2

Decide the version number for each change from version 1.1.0, and explain: (a) loans.csv gets a new required column, and old files must be converted; (b) a crash when the data folder is missing is fixed; (c) a new report of the most-borrowed items is added.

3

A teammate says, "The code has docstrings, so we don't need a user guide." Explain why they serve different readers, using LendIt.

Check your understanding

Quiz

1.

Which document best helps a volunteer in the middle of a busy Saturday?

2.

Which is the best first line of a user-guide step?

3.

LendIt 1.1.0 gets only a bug fix. What is the next version?

4.

What does "1.10.0" > "1.9.2" evaluate to in Python?

5.

Why keep help text in one dictionary used by both the program and the help page?

6.

What should a deployment package for the client contain?

For parents and teachers

Big idea: A4.4 asks students to create clear, maintainable external user documentation (help files, training materials, manuals); B1.3 asks them to produce the software to specification, including deployment, user documentation and training materials. This lesson covers documents for each audience, task-based writing, single-source help text, a short training session, and packaging a versioned release.

How to help: Be the brand-new user. Try to do two tasks using only their quick reference card while they watch silently and take notes. Ask to see the release notes and the README before they install the program anywhere.

Common difficulties:

  • Writing for programmers (function names, variables) instead of users.
  • Forgetting troubleshooting: users mostly open documentation when something has gone wrong.
  • Documentation that is out of date with the program.
  • Shipping test data, passwords or the whole repository to the client.