Experiment template in Markdown: one change, one file

This experiment template records one bounded try of a change in Markdown: the question you started with, what you expected, what you did, what you saw, and what you choose next. Keep one plain .md file for that one change.

People can use this template for work pages written by hand or for pages from AI agents. You write the expectation before the attempt and describe the result afterward. Both go in the same experiment file. Use your existing text editor for the writing.

Experiment rationale

Here an experiment file concerns one planned change over a stated span of time. You record the attempt as well as what came of it, with the expectation kept apart from what you actually saw.

In the brainstorm template, you collect ideas for a question, group them, and end at Picked to try. You can take one picked idea into an experiment file of its own and describe the attempt there.

Using a decision record, you describe a choice, the reasons behind it, and the options you turned down. In this experiment file, you describe trying one change and then choose what to do with that result.

In the postmortem template, you write about a problem after someone has found and fixed it, including the causes and follow-up actions. Here you start with a planned attempt and an expectation before writing about what happened.

Template anatomy

Use the following block as this post's template for an experiment write-up. Replace the instructions with your own account of a single attempt. Start with the question and expectation; fill in the attempt, result, and next action as you do the work.

# Name the change in a few words

## Question

Ask one question about the change in one line.

## What we expected

Describe the expected result in one or two sentences.

## What we tried

Describe what changed, for how long, and who ran the try.

## What happened

Describe what you saw, with any whole-number figures inside sentences.

## What we do next

- Keep: name something to retain from the attempt.
- Drop: name something to stop after the attempt.
- Try again: name a further attempt.

Here is the purpose of the title and the five headings in this template:

• Title. Name the particular change you intend to try. In the sample, the change is a one-line summary placed first on a project page.
• Question. Ask about the one change you plan to try. Give it one line, as in the question about project-page summaries in the sample.
• What we expected. Put the expectation into one or two sentences before describing the attempt. In this template, you keep that expectation separate from the later account of what you saw.
• What we tried. Describe the change and its duration, naming whoever runs the attempt in plain sentences. For the sample, John Doe runs the attempt for four weeks.
• What happened. Describe what you counted or observed, using whole numbers within the account. Jane Doe gives three figures there: the pages she read, the summaries that named the current task, and the summaries that described a project.
• What we do next. Give a keep, drop, or try-again action its own dash line. The block leaves a place for those three kinds of action, with wording to replace for your attempt.

Doe scenario

For this made-up sample, the office change takes place at Doe Holdings. Jane Doe is the writer of the experiment file, and John Doe runs the attempt. The change concerns a short summary at the beginning of a project page.

# Doe Holdings project-page summaries

## Question

Can we name the current task in a one-line project-page summary?

## What we expected

We expected to name the current task in one sentence at the top of a project page.

## What we tried

John Doe added a one-line summary to the top of 20 project pages for four weeks.

## What happened

Jane Doe read the 20 pages after four weeks. Jane Doe found a current task in 12 summaries and a project description in 8 summaries.

## What we do next

- Keep: we retain the one-line space for the current task.
- Drop: we remove the project description from that space.
- Try again: John Doe writes a current-task sentence for the 8 pages with project descriptions.

The sample has five section headings beneath its title, one question line, one expectation sentence, and three action lines. Jane Doe accounts for 20 summaries: 12 name a current task and 8 describe a project. She describes what she found without saying that the change achieved the expectation.

In the last part, John Doe has a further attempt for the 8 pages with project descriptions. The next action stays tied to what Jane Doe read, while the earlier expectation remains above the account of the attempt.

Brevity principles

These four tips describe this template's aims for the question, expectation, figures, and next action:

• One question line. Keep the question to one change you intend to try. The sample asks about naming the current task in a one-line summary, rather than describing the whole project.
• A brief expectation. Use one or two sentences for what you expect to see. The sample uses one sentence about naming the current task before the rest of a page.
• Figures within the account. Keep each number in a short sentence beside what you counted. Jane Doe names the 20 pages she read, then describes the 12 current-task summaries and the 8 project descriptions.
• A short action line. Put a keep, drop, or try-again action on a dash line. In the sample, the further attempt names John Doe and the 8 pages he will work on.

Filename convention

For this template, give one experiment its own .md file and choose a dated name for the attempt. For year-first dates and hyphen-joined words, read the file naming post. For the sample, a name such as 2026-10-22-project-page-summary.md combines that date shape with words for the change.

Use the words after the date to name the attempt you describe under What we tried. Here those words concern the project-page summary, the same change named in the sample's title. With that name, the attempt has one file of its own among the other .md files in the folder.

Where Sashmark fits

For people keeping .md work from AI agents, the plan for Sashmark is a desktop Markdown reader with editing built in. The whole reader is in development, and no part has come out. A project folder containing experiment files alongside other .md work is the kind of folder Sashmark is planned for.

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

Visit sashmark.com.