Turn a rough note into a useful how-to guide

Improve one documentation page by defining its reader, writing a workable sequence, and making the result easy to recognize.

Name the reader and the result

Choose a task someone already needs to complete. A page called “Export a project list” gives the writer a clear boundary. State who the page is for, what they need before starting, and what they should have at the end. Google’s Technical Writing One course treats audience and scope as core writing skills; GOV.UK’s content guidance begins with user needs.

Write an opening sentence you can verify: “Use this guide to download a CSV of the projects you can access.” This is a fictional example. If the task depends on an account role or software version, say so before the first action.

Sources: Google: Technical Writing One introduction, GOV.UK: Writing to GOV.UK standards

Give the page one main job

Diátaxis separates documentation into tutorials, how-to guides, reference, and explanation. Use that distinction to give a page a main purpose. A tutorial helps someone learn through a guided activity. A how-to guide supports a task. Reference records details, while explanation develops understanding.

For the fictional export task, the steps belong on the how-to page. Put the complete column dictionary in reference and link to it where a reader needs it. Keep the reasoning behind the export format in an explanation. These connections let readers choose their depth while preserving a clear route through the task.

Sources: Diátaxis overview

Write steps that survive a fresh start

Follow the task in the product while editing. Begin from the starting point named in the introduction, and capture the actions in their actual order. Use the visible labels for controls. Give each step a clear action, and include the location when it would otherwise be ambiguous. If a decision changes the next action, explain that decision where it occurs.

For code examples, identify the environment and mark every value the reader must replace. Supply small fictional inputs that make the example understandable. A copied command and its expected output should look different. Ask whether a person opening this page tomorrow could tell what to change, what to run, and what to leave alone.

Sources: Diátaxis: How-to guides, Google developer documentation style guide: Procedures

Show how to recognize success

After a meaningful action, describe an observable result. In the fictional export guide, the final check might be opening the downloaded file and confirming that it contains the expected column headings. Verify that result before presenting it as actual product behavior. Words such as “finished” or “working” need something the reader can inspect.

Add troubleshooting for problems you have evidence for. Pair each symptom with a supported next step, and distinguish a confirmed cause from a possibility. If a failure needs another person's help, state what information would help them investigate. Keep that information limited to what the task requires.

Sources: Google developer documentation style guide: Procedures

Make the next edit easy

Review the page with someone who matches its intended audience. Give them the stated task and let them work from the draft. Record where they pause, infer a missing step, or interpret a term differently. Those observations give you specific edits to make; they do not establish that every reader will have the same experience.

Finish with a maintenance note in your working records: the feature or version checked, the review date, and who owns the page. When the product changes, revisit the affected instructions and examples. A useful guide stays connected to the behavior it describes, one small revision at a time.