Markdown product specification template
A .md file ready to fill in: problem, goal, out of scope, flow, acceptance criteria, open questions and decisions. It opens in any editor and shows formatted in Marko.
Why a spec in Markdown
A specification describes what you are about to build before any code is written. In Markdown it is a plain text file: it opens anywhere, on any Mac, with no proprietary software. You keep it next to the repository, track its versions with Git, and every review shows in black and white what changed since the last one.
What each section is for
Seven sections, in the order a team reads a spec.
- Problem: who hits what, and why it is a problem today.
- Goal: the expected outcome, in one measurable sentence.
- Out of scope: what the spec does not cover, to head off false expectations.
- Proposed flow: the steps the person involved goes through.
- Acceptance criteria: verifiable conditions, as checkboxes.
- Open questions: what is still to settle.
- Decisions: what was settled, by whom, when.
How to fill it in
- Download the template, then open it in Marko (right click, “Open with”, “Marko”) or in the editor of your choice.
- Replace each example line. Delete the sections you do not need: a short spec reads better.
- If you already have an AI reply, paste it in Source mode, then move each idea into its section.
- To send it to someone who does not have Marko, use “Export as PDF…” in the File menu.
Write acceptance criteria you can verify
This is the section that separates an intention from a spec. A verifiable criterion is either met or not, with no argument. Compare “the form should be fast” with “the form submits in under two seconds on a normal connection”. The first can be debated forever; the second can be tested. Go back over each line in the section until you can answer it with a plain yes or no.
If you start from an AI reply, paste it in Source mode, then move each idea into its section. What read like a summary becomes a run of criteria and decisions the team can follow. Marko shows the result formatted while you reorganise.
File preview
# Spec: [feature name] - **Author:** First Last - **Status:** draft / in review / approved - **Last updated:** YYYY-MM-DD ## Problem Who hits what, and why it is a problem today. ## Goal The expected outcome, in one measurable sentence. ## Out of scope - What this spec does not cover ## Proposed flow 1. First step of the flow 2. Second step ## Acceptance criteria - [ ] Verifiable condition 1 - [ ] Verifiable condition 2 ## Open questions 1. First question to settle ## Decisions > Decision: what was settled, by whom, when.
Checkboxes and the quote show in Marko and in most Markdown editors. A plain text editor shows the symbols as they are.
To share the spec, export it to PDF from Marko: the formatting and the checked boxes are kept, and the document reads without installing anything.
Frequently asked questions
How is this different from a product brief?
The brief says why the project is worth doing and what it aims for; the spec describes what you will build, with acceptance criteria and out of scope. Both templates sit side by side.
What sections does the template hold?
Problem, goal, out of scope, proposed flow, acceptance criteria, open questions and decisions.
How do I send the spec to someone who does not have Marko?
Export it to PDF from the File menu. The formatting and the checked boxes are kept.
Download the template, then open it in Marko. The .md file opens formatted. Fill it in, then share it or export a PDF.
Full 14-day trial, no account or credit card. See pricing