Skip to content

How we write specs at Folio.

One page, four headings, and a section called “Not doing” that saves more time than the rest combined. Our spec template, with the reasons behind it.

JEdited by JonasOct 15, 20265 min read

We write a spec for anything that takes more than a week. That is about two a week across the company. They all look the same, which is the point: you know where to look before you start reading.

Four headings

  1. Problem. Who has it, how we know, and what it costs them. One paragraph, with a link to the evidence.
  2. Not doing. What this spec will not solve, even though someone will ask.
  3. Proposal. What we will build, drawn if possible, with the smallest version first.
  4. Open questions. Things we do not know yet, each with an owner and a date.

There is no “Background” and no “Goals” section. Background turns into history nobody needs. Goals turn into a list of nice words. The problem paragraph does both jobs in fewer lines.

The section that saves a week

“Not doing” is the section people skip in their first month and defend in their second. Writing down what is out of scope before the review means the review argues about the proposal, not about everything the proposal could have been.

Example, from the verified pages spec: Not doing: approval workflows, more than one owner per page, verification of individual blocks. Each of these came up. Each was already answered.

Reviews happen in the margin

A spec is shared with the people it affects and gets two working days of comments. If the comments agree, the author resolves them and starts. If they disagree, we meet for 25 minutes with the page open, and the decision is written into the page before anyone leaves.

  • Done: Draft shared with engineering, design and support
  • Done: Two days of comments
  • Done: Disagreements resolved in the page
  • To do: Status set to Building in the Specs database

A close cousin is in the gallery as Product spec, written by the Pallet platform team: the same problem-first order, plus a decision log reviewers sign. It is one of the most copied templates we have.

J

Written by

Jonas Brandt

Co-founder, CTO, Berlin. Owns the page “Architecture notes”.

All posts

Keep reading

More from the blog.

Every post
  • Writing4 min

    Meeting notes that turn into work.

    Most meeting notes are a transcript nobody opens again. Three small habits turn them into decisions, owners and dates that land in the right table.

    MMarta Silva

  • Writing6 min

    Write for the person who joins next year.

    The best test for any document is a reader who wasn’t there and can’t ask. Notes on writing for them, from five years of building a place to write.

    IInes Duarte

Write it down once. Find it forever.

Folio is free for personal use. Teams pay per member who edits, and guests are always free.