How to write a user manual

1. Plan around reader tasks

Start with the product, version, and reader. A first-time user setting up a device needs a different path from someone maintaining it. List the tasks each reader needs to complete, then make each task a topic with a descriptive title.

A useful starting outline is: what the product does; what is needed before starting; setup; everyday tasks; care and maintenance; troubleshooting; and product-specific reference information. Include only the sections that help someone use your product.

In Manual Tools, create the manual and add topics in that order. Nest a topic when it explains part of a larger task. Readers can navigate the table of contents or search a published manual.

2. Write steps readers can test

Give each task a clear starting condition and an expected result. Put required tools, access, materials, or prerequisites before the steps. Use the names readers see on buttons, labels, and screens.

Write one action per numbered step. For example, “Choose Publish” is more useful than “Finalize the document.” Follow the action with the result when readers need to know what to check. If a task branches, explain how to choose the next path.

For the publishing workflow, a testable instruction is: “In the editor, choose Publish. Select reader visibility and indexing, then confirm. Open the reader link after publication completes and check the topic.” The example manual puts that workflow in context.

3. Show the important details

Use an image when it shows something a sentence cannot explain clearly: a connector, a component location, a screen, or the expected result. Add labels or a caption where readers need help identifying a detail. Write useful alternative text so the essential information is available without the image.

Keep the instruction in the topic text as well as any video. Readers may be viewing a PDF, using assistive technology, or working without audio. Put reference data in a table when it makes values and units easier to compare.

Check that the product and software version shown in the media match the instructions. Upload media to the selected manual, then insert it through the editor.

4. Review the instructions against the product

Have someone follow the draft from its stated starting point. Record where they pause, ask a question, or get a different result. Review with a person who knows the product, and use qualified review for safety-critical procedures.

Identify the source of technical claims and specifications. Prefer current product documentation and direct testing for the relevant model. Name the author or publishing organization in the manual, explain its role, and give readers a way to report a correction.

• Do the steps work in the order written?
• Are labels, units, product names, and versions consistent?
• Are prerequisites and safety information in the right place?
• Do images, links, and troubleshooting suggestions match the task?
• Can a reader identify who is responsible for the instructions?

Use revision history to review earlier saves. The integrity checker on the paid plan can help find document issues, while a product review establishes whether the instructions are correct.

5. Publish an identifiable version

Choose public or private readers deliberately. Enable search indexing only when the manual is intended to be discoverable through search. Drafts remain private until publication; saved changes do not replace a published release automatically.

Open the published guide and check its navigation, images, links, and search. Generate a PDF from the published release and check the pages readers will download. Keep a backup before a substantial rewrite.

When the product changes, update its version and the affected topics. Review the changes before publishing again. For translations, check terminology and steps in the target language as well as whether the source topics have changed.