How-to guide template in Markdown: goal, steps and fixes

Here, a how-to guide is one .md file in which you teach a person one task, and the how-to guide template is the starting block for that file. You write the file one time, keep it, and come back to it the next time that task turns up. It holds the task's name, the reason for the task, what you need first, numbered steps, what to do if a step fails, and the name of whoever keeps the page.

Coming up: the template with a sentence or so on each of its parts, an invented sample, five tips on length, and a pattern for the file name. There's only text in the file, so you can type it up in whichever text editor is on your computer.

A how-to guide beside other step files

A person reads a how-to guide's steps from the top and carries them out in that order. The template could also go by the name step-by-step guide template: you fill it in for one job, then keep the file for whoever does that job next.

A task file written for an AI agent to work through is the subject of a post on task files for agents. A how-to guide, by contrast, is for a person to read and follow.

Numbered steps turn up in the bug report template as well, written there so someone else can make one problem show up again. In a how-to guide, the steps take a person through one whole task.

Template for one how-to file

Below is this post's template. Create a fresh .md file, drop the whole block in, then write your own wording over every placeholder.

# How to do the task, in a few words

## Goal

One sentence on what the task is for.

## Before you start

- One thing you need before step 1
- Another thing you need before step 1

## Steps

1. The first action.
2. The next action.
   A short line here, only when a step needs more.
3. The last action.

## If it goes wrong

- A sign that something is off: what to do about it
- Another sign: what to do about it

## Who keeps this page

- Kept by: Name
- Date last walked through: YYYY-MM-DD

The parts, in the order they appear:

• Title line. A level-one heading opening with the words How to, followed by the task in a few words.
• Goal. A single sentence that says what the task is for.
• Before you start. A dash line per item you need on hand ahead of step 1.
• Steps. Numbered lines in the order you carry them out, each holding one action. Under a step that needs a few more words, a short indented line follows; other steps go without one.
• If it goes wrong. A dash line per problem, giving the sign first, then a colon, then what to do.
• Who keeps this page. Who keeps the page up to date, and the date someone last walked through the steps from top to bottom.

The template's steps make up a numbered list, with an indented line under step 2. How Markdown sets the start number of such a list, and the indent a line under a step needs, are both in the numbered list post.

Closing the office at Doe Holdings

Every name and detail below is invented, and Doe Holdings is too. In the sample, Jane Doe writes down how to close the office for the night, and John Doe keeps the page.

# How to close the Doe Holdings office for the night

## Goal

You leave the office with the lights off, the alarm on and the back door locked.

## Before you start

- You have the back door key with you.
- You are the last person in the office.

## Steps

1. Turn off the lights in each room.
2. Write your name on the sign-out sheet by the back door.
3. Turn on the alarm by the back door.
   You hear a short beep once the alarm is on.
4. Leave through the back door.
5. Lock the back door behind you.

## If it goes wrong

- You cannot turn off a light: write which light on the sign-out sheet, next to your name.
- You cannot turn on the alarm: lock the back door anyway and tell John Doe the next morning.
- You cannot lock the back door: stay by the door and call John Doe.

## Who keeps this page

- Kept by: John Doe
- Date last walked through: 2026-10-21

Counting the sample: five numbered steps, two dash lines under Before you start, and three under If it goes wrong. Step 3 alone has an indented line beneath it. The 2026-10-21 date under Who keeps this page is written year first.

Five tips on page length

This template aims to keep the page short, and the five tips here come straight from its lines and the sample's:

• One task to a page. The template's title line holds a single task, and so does the sample's: closing the office for the night.
• One action to a step. Every step holds one action, in the sample and the template alike, such as turning off the lights or locking the back door.
• An indented line only where needed. The template has a single indented line, under step 2, and the sample's single indented line sits under step 3.
• A sign, then what to do. Each line under If it goes wrong starts with a sign and, after a colon, says what to do. The template's two lines and the sample's three all follow that order.
• Who keeps it, and when it was last walked through. The template has room for both under Who keeps this page, and the sample has John Doe and 2026-10-21 there.

Naming a how-to file

One task, one .md file. Give it a name built from a few hyphen-joined words that describe the task, as in close-the-office.md. The date of the last walk-through goes inside the page, under Who keeps this page, and the file name has no date in it.

Keeping names short and unchanged, and leaving a date out of some file names, are topics in the post about Markdown file names.

Where Sashmark fits

Planned as one piece of desktop software for both reading and editing Markdown, Sashmark is intended for people whose .md pages come from AI agents. No piece of the software is out yet, as all of it is in development. A project folder holding how-to pages next to that project's other .md files counts as one set of files Sashmark is planned for.

See the planned features, the help pages and the roadmap for where each part stands.

Visit sashmark.com.