# How to document a process so it still works when someone else runs it

> How to document a process in seven steps, with a template, a cheap way to test it cold, and where the file should live so people and assistants read one copy.

Source: https://baalda.com/blog/how-to-document-a-process
Site: Baalda, https://baalda.com
Published: 2026-10-21

**Short answer.** Pick one process and write down what starts it, what counts as finished and who owns it. Record the steps while someone actually does the work, with a reason beside any odd step. Keep it as one plain file next to the work, then test it by having someone who has never run it follow it cold.

To document a process, write down what starts it, what counts as finished and who owns it, then record the steps while someone actually does the work, with the reason next to any step that looks strange. Then hand it to a person who has never run it and watch where they stop. Everything else is formatting.

The reason most process documents fail is not the template. It is that they are written by the one person who does not need them, and nobody reads them again until that person is on holiday. The process that runs once a quarter is the one that breaks, because by then the only copy of the real version is in someone's memory. This guide covers the writing, the testing and where the file should live, including the reader most guides still leave out: the AI assistant somebody will ask to run it. The worked example for that part is [Baalda](/blog/team-second-brain), a shared vault of plain markdown files, and the guide says plainly where a capture tool or a checklist runner is the better choice.

## How do you document a process, step by step?

1. **Pick one process, not a department.** Choose something that runs often enough to matter and rarely enough to be forgotten: month-end close, a production deploy, offboarding a client, renewing a certificate. Quarterly processes are the best first candidates, because nobody remembers them.
2. **Write the trigger and the finish line first.** "When an invoice over 5,000 arrives" and "done when it is approved and filed" are the two lines that stop the document sprawling into the processes either side of it.
3. **Name one owner.** Not a team. A person who is allowed to change the document and who gets asked when it is wrong.
4. **Record the steps while someone does them.** Sit with the person who runs it, or have them write as they go. Ask what they actually do, not what they should do. Improvements can wait for a second pass.
5. **Write the reason beside every odd step.** "Restart the worker before the migration, not after, because the old worker holds a lock on the jobs table." The reason is what stops the next person deleting the step as a mistake.
6. **Link, do not copy.** If a step uses a template, a spreadsheet or a login, link to where it lives. A copy pasted into the document becomes a second version that drifts from the first.
7. **Test it cold.** Give it to someone who has never run the process and say nothing. Every question they ask is a missing line.

## What should a process document include?

Short is better than complete. A process document that fits on one screen gets read, and one that needs scrolling gets skimmed by everyone except the person who wrote it. This is a template that covers most processes a team of five to fifty runs:

```markdown
# Month-end close

Owner: Sara
Trigger: first working day of the month
Done when: the ledger is locked and the summary is posted in #finance
Last run: 2026-10-01 by Omar

## Before you start
- Access you need: the accounting system (admin), Finance/Reports
- Inputs: bank exports for all three accounts

## Steps
1. Download the bank exports. Use CSV, not PDF, because the import rejects PDF.
2. Run the reconciliation template in Finance/Reports/reconcile.xlsx.
3. Anything over 500 unmatched goes to Sara before you lock the ledger.
4. Lock the ledger and post the summary.

## If something goes wrong
- Import fails on a date column: the bank changed its export format. See the note from 2026-07.

## Why it works this way
- We lock on day one rather than day three because the payroll run reads the locked ledger.
```

Two lines in there do most of the work. **"Access you need"** is the line that a writer with full access never thinks to add, and it is the first thing a new runner trips over. **"Last run"** tells the reader whether the document has been through reality recently or is a description of how things worked last year.

If your team has nothing written today, the wider question of what to write down and what to leave in the files you already have is covered in [the internal documentation guide](/blog/internal-documentation). A process document is the most useful single kind of it.

## Where should a process document live?

Next to the work, in a format both kinds of reader can open. In 2026 a process document has two readers: the person who runs it, and the assistant that person asks for help halfway through. A document the assistant cannot reach gets replaced by the assistant's guess, which is confidently general and wrong about your accounts.

This is the problem Baalda is built around. A Baalda vault is a folder of plain markdown files on each member's own disk, edited by several people at once in real time, with AI clients reading and writing the same files over MCP. A process document is just `Processes/month-end-close.md`. The person running it has it open, the owner can fix a step while they watch, and an assistant connected to the vault reads the same file rather than a copy that was pasted into a chat three months ago.

Permissions are set per folder or per file, with three levels: Can edit, Can view and No access. A sensible default for process documents is that everyone who runs them can view them, and the people who run them regularly can edit them, so the fix happens in the document rather than in a chat thread.

The usual alternatives are fine and worth naming. A Confluence or Notion page works if your team already lives there, and [the Confluence comparison](/compare/confluence) is honest about where Confluence is the better choice. The difference that matters for process documents is whether an assistant can read the page under the same rules as a person, and whether the text stays yours if you leave the tool.

## How do you test a process document before you need it?

Every guide says to hand the document to someone who has never run the process. It is the right advice and almost nobody does it, because it costs a colleague an afternoon for a process that will not run for another two months.

There is a cheaper first pass. Ask an assistant to follow the document cold, **with the same access as the person who will actually run it**, and list every point where it had to guess. An assistant has none of your tacit knowledge. It does not know the bank changed its export format in July, or that "the template" means the one in Sara's folder. That ignorance is what makes it a good first reader.

The part that makes the test honest is the access. In Baalda, an MCP token authenticates an AI client as one user within one vault, and the note tools only return what that user is allowed to read. So connect the assistant as the person who will run the process, not as the vault owner:

```bash
claude mcp add --transport http baalda https://api.baalda.com/api/mcp \
  --header "Authorization: Bearer mcp_…"
```

The token is created in the app under **Vault settings → MCP** by the person whose access you want to test. For a self-hosted server, the endpoint is your server URL plus `/api/mcp`. Then ask something plain:

```text
Read Processes/month-end-close.md and follow it as if you were running it
today. Do not do anything. List every step where you could not tell what
to do, every link you could not open, and every term the document does
not define.
```

What comes back is usually three kinds of gap. Terms only the writer understands. Steps that assume a previous step happened somewhere else. And links that resolve for the owner and dead-end for everyone else, because the reconciliation template sits in a folder the runner has No access to. The last kind is the one a full-access reviewer never finds, because for them every link works.

This does not replace the human test. An assistant will not notice that a step is physically awkward, or that the person who approves the payment is never online on Mondays. It catches the gaps that are visible in the text, which is most of them, before a colleague spends an afternoon on it. The same question for new hires, where the reader also turns over every time, is covered in [the onboarding documentation guide](/blog/onboarding-documentation).

## Why do process documents go out of date?

Because the fix happens somewhere else. The runner hits a broken step, asks in chat, gets unblocked in four minutes and moves on. The answer lives in a thread, the document stays wrong, and the next person asks the same question.

Three habits stop most of it:

- **Fix it in the run.** Whoever runs the process edits the document as they go, while the reason is fresh. That is why the people who run a process should be able to edit it, not only the owner.
- **Update "Last run" every time.** It takes five seconds and it is the cheapest freshness signal there is. A document last run fourteen months ago should be read with suspicion.
- **Keep the reasons.** Most bad edits to a process document are someone deleting a step that looked unnecessary. A one-line reason beside it is what stops that.

When the person who owns a process leaves, the document is the handover, and [the knowledge transfer guide](/blog/document-knowledge-transfer) covers what changes when the handover is an access change rather than a pack written on someone's last day.

## Which tool fits which kind of process?

Different processes want different tools, and the honest answer is that one team often uses two.

| The process is mostly | Use | Why |
|---|---|---|
| Clicking through a software UI | A capture tool such as Scribe | It records the clicks and turns them into a step guide with screenshots, which is faster than writing it |
| A recurring checklist with assignees and due dates | A checklist runner such as Process Street | Each run is tracked, assigned and approved, which a document cannot do |
| Judgement, order and reasons, read by people and assistants | Plain markdown in a shared vault, such as Baalda | The reasons stay with the steps, the team edits in place, and an assistant reads the same file under the reader's access |
| One part of a large existing wiki | Your wiki | Moving one page out of Confluence or Notion costs more than it saves |

## Where does Baalda not help?

Baalda is a place to keep and edit process documents. It is not a process tool, and several things a process tool does are missing:

- **No screen capture.** It will not record your clicks or generate screenshots. For a UI-heavy process, a capture tool is quicker, and you can link the guide from the markdown file.
- **No checklist runs.** There is no assigning a run to a person, no due dates and no approval step. If you need to prove each run happened, use a runner.
- **No diagrams.** There is no flowchart editor. A numbered list is usually clearer than a flowchart for a linear process, but branching processes with many decisions can genuinely want one.
- **No review reminders.** Nothing nags the owner when a document has not been touched in a year. "Last run" is a convention you keep, not a feature.
- **It does not write the document.** An assistant can test a draft and suggest fixes, but the steps and the reasons still come from the person who does the work.

The short version: write the trigger, the finish line and the owner, record the steps as someone does them, keep the reasons, and test it cold before the day you need it.

## FAQ

### How do you document a process?

Choose one process, write its trigger, its finish line and its owner, then record the steps while the person who runs it does the work. Add the reason beside any step that looks strange, link to templates and files instead of copying them, and test the result by giving it to someone who has never run the process.

### What is the best format for process documentation?

A short numbered list in a plain text or markdown file covers most processes, with sections for the access you need, the steps, what to do when something goes wrong, and why it works this way. Use a screen capture tool for click-by-click software walkthroughs and a checklist runner when each run needs an assignee, a due date or an approval.

### Can an AI assistant test a process document?

It can do a useful first pass. Ask it to follow the document without acting and list every step, link and term it could not resolve. The test is only honest if the assistant has the same access as the person who will run the process. In Baalda an MCP token signs the assistant in as one user, so it sees exactly what that user can read.

### How do you keep process documentation up to date?

Let the people who run a process edit it, and have them fix broken steps during the run rather than in a chat thread. Record who ran it last and when, so readers can see whether it has met reality recently, and keep a one-line reason beside steps that look unnecessary so they are not deleted by mistake.