DoAssignment.ca

DoAssignment study guide

A4.4 · Write maintainable user documentation

Learn to write maintainable user documentation through clear examples and targeted practice.

Ontario Grade 12 Computer Science

Programming Concepts and Skills

ICS4U A4.4 study lesson

A program can work correctly and still be difficult to use if people cannot work out what it does or how to use it. User documentation helps its intended audience understand the program and complete common tasks. In this lesson, “maintainable” means that the documentation can be checked, corrected, and kept useful as the program changes. You will practise deciding what a reader needs, writing usable directions, and reviewing a short guide for gaps. The examples focus on the reader’s experience, not on programming the applications described.

What you will learn

  • Explain the purpose of user documentation and how it differs from instructions meant for the program’s developers.
  • Plan user documentation around the needs and tasks of the intended audience.
  • Write clear, accurate instructions that a reader can follow without guessing.
  • Review and update documentation when the program or its use changes.

1. Start with the user and the task

ICS3U provides experience with writing programs and using them to solve problems. For this expectation, the focus shifts from how a program is built to how a person uses it. User documentation is information intended to help users understand a program or complete tasks with it. It may include a brief description, instructions, explanations of inputs, or help for a problem the user may encounter.
Begin by identifying the intended reader and what that reader is trying to do. A guide for someone opening a program for the first time may need to explain how to begin. A guide for a regular user may focus on a particular task. Do not assume every reader knows the program’s terminology or already understands its controls.
Select information that helps the reader act. A list of every feature may be less useful than a short set of instructions for the task the reader came to complete. Consider what the reader needs to know before starting, what action to take, and what they should see or understand afterward. If a required detail is unknown, verify it with the program or its responsible team rather than inventing an answer.
  • Identify the audience and its likely task before drafting.
  • Include information that helps users understand or use the program.
  • Check facts about the program instead of guessing.

2. Make instructions clear and usable

Write instructions in a logical order. Each step should tell the reader what to do, using names that match the program’s visible controls. If a reader must choose an item before continuing, say which item to choose. Avoid directions such as “do the usual thing” or “continue as needed”; they leave the reader to guess.
Use familiar words where possible. When a program uses a necessary term that may be unfamiliar, explain it briefly at the point where it matters. Keep one instruction focused on one action when that makes the sequence easier to follow. Separate preparation, actions, and the expected result so readers can find the part they need.
Describe expected results accurately. For example, if the user saves a form, say what confirmation the program actually provides, if any. Do not promise a message, button, or outcome that has not been checked. If a task can fail under a relevant condition, explain what the user can do next, but only when that advice is known to be correct.
A useful review question is: could a reader follow this instruction without asking the writer what a vague word means? Another is: does the described result match the program? These checks help improve clarity without adding unnecessary material.
  • Put actions in the order the user performs them.
  • Use control names and descriptions that match the program.
  • State expected results only when they are accurate and verified.

3. Keep documentation maintainable

Documentation is maintainable when it is practical to review and revise without losing accuracy or clarity. Organize information under descriptive headings, keep related instructions together, and avoid repeating the same directions in several places. If a feature changes, repeated copies can become inconsistent; a clear, compact guide makes it easier to find what needs attention.
Review the guide against the current version of the program. Check that every named control still exists, the steps still work as described, and the stated results remain accurate. When the program changes, identify which instructions the change affects and update those parts. Remove or revise information that is no longer true.
A reader can also help reveal unclear wording. Ask someone who represents the intended audience to follow a task using the guide. Observe where they hesitate or interpret a direction differently than intended. Treat that as evidence that the wording may need improvement; do not assume the reader is at fault. This review is about the usefulness of the instructions, not a claim that the guide has been formally tested.
Keep the scope appropriate. User documentation explains what users need to know to use the program; it should not become a description of internal programming details unless those details are needed by its intended readers. The right amount of detail is enough to make the task understandable, without burying it in unrelated information.
  • Use headings and grouping that make information easy to locate.
  • Check the guide whenever relevant program details change.
  • Use reader feedback to find unclear or missing instructions.

4. A practical drafting and review routine

A simple routine keeps the work focused. First, name the intended audience and the task. Next, list the information the reader needs before, during, and after that task. Draft the directions in the order the reader will use them. Then compare each statement with the program to check its accuracy. Finally, review the guide’s organization and revise any vague, repeated, or out-of-date wording.
This routine is not a rigid template. A short guide may need only a purpose statement and a few steps. A guide for a larger set of tasks may need several headings. In either case, each part should serve the reader. The examples below demonstrate how to apply these decisions to fictional program features; they do not claim that any program or instructions were tested.
  • Plan, draft, verify, and revise with the audience’s task in view.
  • Match the size and organization of the guide to the information users need.
  • Keep examples and expected results grounded in known program behaviour.

Worked example

Documenting a fictional reading list

A fictional reading-list program lets users add a title by entering it in a box labelled “Title” and selecting “Add”. Draft a short instruction for a new user without claiming an unverified result.
  1. Identify the reader’s task
    The reader wants to add a title. The given control names are known, so the instruction can use those exact names.
  2. Write the action in order
    A concise direction tells the reader what to enter and which control to select. Do not add an outcome such as a confirmation message unless that behaviour has been verified.
Answer: To add a title, enter it in the “Title” box, then select “Add”.
Check: The instruction uses only the controls and behaviour stated in the problem. It does not invent what appears after selection.

Worked example

Finding a missing instruction

A fictional room-booking guide says, “Choose a room and select ‘Continue’.” The program also requires users to choose a date, but the guide does not mention it. Improve the direction using only these facts.
  1. Compare the directions with the task
    The original wording omits a required choice. A reader following it may not know that the date is needed.
  2. Include the missing action
    Add the date selection before the final control, while avoiding unsupported details such as date format or availability rules.
Answer: Choose a date and a room, then select “Continue”.
Check: The revised direction includes both stated requirements in a usable order and does not invent additional rules.

Worked example

Updating a guide after a control changes

A fictional program renames its “Export” control to “Download”. Its guide has two separate task instructions that refer to “Export”. Describe a maintainable update.
  1. Locate affected wording
    Both instructions name the changed control, so both need review. Updating only one would leave the guide inconsistent.
  2. Revise and verify
    Replace the old name where it refers to this control, then check both instructions against the current program. Keep any surrounding directions only if they remain accurate.
Answer: Update both task instructions to use “Download”, then check that each direction still matches the current program.
Check: The update covers both known references and includes an accuracy review rather than assuming the rename was the only relevant change.

Common mistakes and how to avoid them

Writing instructions from the developer’s point of view, using unexplained internal terms.
Correction: Use the intended user’s task and explain any necessary unfamiliar term.
Assuming readers will infer a missing step or interpret a vague direction correctly.
Correction: State required actions in order and replace vague wording with a specific direction.
Describing a confirmation or result that has not been checked.
Correction: Verify program behaviour before documenting it; otherwise, do not promise that result.
Changing one reference to a control name while leaving other instructions out of date.
Correction: Review all affected parts of the guide and check them against the current program.

Lesson summary

  • User documentation helps its intended audience understand or use a program.
  • Plan around a real reader and task; make directions clear, ordered, and accurate.
  • Organize information so it is easy to locate and revise.
  • When program details change, review and update every affected instruction.

Check your understanding

Question 1

A guide says “finish the setup as usual.” What is the best revision approach?
  1. Keep the sentence because regular users will understand it.
  2. Identify the intended reader and replace the vague phrase with the known setup actions in order.
  3. Add technical details about how the program was built.
  4. Promise that setup always succeeds.
Show answer and explanation
Identify the intended reader and replace the vague phrase with the known setup actions in order.
The phrase “as usual” is unclear to readers who do not already know the process. Replace it with accurate, task-focused directions.

Question 2

A control’s name changes in the program. What should the documentation writer do?
  1. Update only the first occurrence of the old name.
  2. Leave the guide unchanged if its general purpose is still clear.
  3. Find affected instructions, revise them, and check that they still match the program.
  4. Add a new feature description unrelated to the change.
Show answer and explanation
Find affected instructions, revise them, and check that they still match the program.
Reviewing all affected instructions helps keep the guide consistent and accurate.

Question 3

Which statement is safest to include in a guide?
  1. “A success message always appears,” when that behaviour has not been checked.
  2. “Select ‘Save’,” when the program visibly labels the control “Save”.
  3. “The program will never lose your work,” without evidence.
  4. “Choose any option,” when a particular option is required.
Show answer and explanation
“Select ‘Save’,” when the program visibly labels the control “Save”.
Using a verified control name is specific and grounded in known information. The other choices make unsupported or inaccurate claims.

Key terms

User documentation
Information that helps the intended audience understand or use a program.
Intended audience
The people a particular guide or set of instructions is written to help.
Maintainable documentation
Documentation that can be reviewed and revised while remaining organized, clear, and accurate.

Continue through ICS4U

View the complete ICS4U Ontario Grade 12 Computer Science curriculum and lessons

About this lesson and its review

Published by DoAssignment. This reviewed lesson follows Ontario Grade 12 Computer Science (ICS4U), expectation A4.4. It is a study resource, not an official curriculum publication.

Before publication, content is checked for structure, mathematical or chemical notation, calculations, course boundaries, and readability. Errors can still occur, so corrections are welcomed.

Official curriculum reference

Report a correction or ask a question