Skip to content
Folio

How-To Guide Template (Markdown) for Documentation

A how-to guide template in plain Markdown for a documentation writer. It states the goal in the title, lists what the reader needs, gives numbered steps with an expected result after each, and ends with a check that it worked, the most likely failures and a review checklist. Copy it, download the .md file, or keep it in the repository next to the code it documents.

Free to use, no attribution required (CC0).

Open in Folio demo

How to {{do the task}}
Audience {{Role or skill level of the reader}}
Applies to {{Product, version or environment}}
Owner {{Name or team}}
Status {{Draft / In review / Published}}
Source {{Link to the code, pull request or ticket this guide documents}}
Last reviewed {{YYYY-MM-DD}} by {{Name}}
Next review {{YYYY-MM-DD}}

{{One or two sentences: what the reader will have at the end, and when to use this guide.}}

Start the title with a verb and name the goal. A how-to guide solves one task for a reader who knows the basics. If the reader has to learn first, write a tutorial and link to it.

Before you start

  • {{Access or permission needed}}
  • {{Tool and version installed}}
  • {{Value or file to have at hand}}

List only what the reader cannot guess. Say where to get each item.

Steps

1. {{Verb and object}}

{{What to do, in one or two sentences.}}

{{command}}

Expected: {{what the reader sees when the step worked}}

2. {{Verb and object}}

{{What to do.}}

Warning: {{Anything irreversible or risky about this step, and how to undo it.}}

{{command}}

Expected: {{...}}

3. {{Verb and object}}

{{What to do.}}

One action per step, then the result. Put a warning before the step it concerns. Run every command on a clean environment while you write, and paste real output.

Verify that it worked

  • {{Check 1: a command, a page or a value}}
  • {{Check 2}}

If something goes wrong

Symptom Likely cause Fix
{{Exact error text}} {{Cause}} {{Fix}}
{{Exact error text}} {{Cause}} {{Fix}}

Keep the two or three failures of this task here. Everything else goes to the troubleshooting guide for the feature: {{page name}}.

Next steps

  • Do more: {{related how-to guide}}
  • Look up details: {{reference page}}
  • Understand why: {{explanation page}}

Review checklist

Tick before you ask for a review. Keep the list for the next reviewer or delete it when the page is published.

  • The title starts with a verb and names one goal
  • Someone other than the author followed every step on a clean environment
  • Each step is one action and has an expected result
  • Warnings come before the risky step
  • Examples use fake values: no real tokens, hosts or customer data
  • The source link and the version in the table are current
  • Links work and point to pages that exist
  • Owner, last reviewed and next review are filled in

Revision history

Date Author Change
{{YYYY-MM-DD}} {{Name}} First version

Want to see it as a real wiki page? Open this template in the Folio demo, where it is a normal Markdown page.

How to use it

  1. Step 1: Name one task. Write the title as a verb and a goal ("How to rotate an API key"). Fill in the audience, the version it applies to and the source: the code, pull request or ticket the guide documents.

  2. Step 2: Run every step yourself. Write each step as one action with the command and the result the reader should see. Do it on a clean environment while you write, and copy the output, not your memory of it.

  3. Step 3: Have someone else follow it, then tick the review checklist. A person who did not write the guide finds the missing prerequisite in minutes. Fix what they stumbled on, set the review date and the owner.

What makes a good how-to guide

It solves one task for a reader who knows the basics. A how-to guide is not a tutorial and not a reference. It does not teach the product from zero and does not list every option. If the reader needs to learn first, link to a tutorial; if they need the details of a flag, link to the reference.

Each step is one action with a visible result. The command, then what the reader sees when it worked. When a step can destroy something, the warning comes before the step, not after it.

It names its source and its version. The code, the pull request or the ticket, and the product version it applies to. A reader can then tell whether the guide is still true, and a reviewer knows what to re-check when the code changes.

It has an owner and a review date. Documentation rots quietly. A named owner and a "next review" date turn rot into a task, and a review checklist makes the review the same every time.

More templates

Troubleshooting guideFrom the exact symptom to the cause and the fix, known issues, and what to send to support.SOPPurpose, scope, roles, numbered steps with expected results, exceptions and a review date.API referenceOne endpoint: auth, parameters, runnable request and response, error table, changelog, review list.
All templates

Questions

What is a how-to guide?
A short document that shows how to reach a specific goal in a series of steps. In the Diátaxis framework it is one of four kinds of documentation, next to tutorials, reference and explanation, and it assumes the reader already knows the basics.
How is a how-to guide different from a tutorial?
A tutorial teaches a beginner by guiding them through a safe exercise. A how-to guide helps a competent reader finish a real task. The tutorial explains as it goes; the how-to guide stays on the task and links away for the explanation.
How long should a how-to guide be?
As short as the task allows. If it has more than about ten steps, or two separate goals, split it. A long guide usually hides a prerequisite that deserves its own page.
Should a how-to guide be generated by AI?
An AI assistant can draft the steps from your code and notes, but it cannot run them for you. Run every command yourself, correct the draft, and have another person follow it before you publish.
Where should how-to guides live?
In version control next to the code, so a change to the code and the change to its guide can be reviewed together. A Markdown file in the repository, or a wiki that stores pages as Markdown files in Git, both work.

Updated 13 October 2026.

Docs next to the code, in the same repository

In Folio a how-to guide is a Markdown page stored as a file in Git. Write it in the browser or in your IDE, and the page history shows who changed which step and when. Code blocks, tables and checkboxes render in the editor. You can write the first draft by hand, ask the built-in assistant to draft it, or let an MCP client read and update the page with a personal token. Either way you read it, run it and edit it before it counts.

Open in Folio demoInstall FolioFolio on GitHub