Skip to content

Notes on writing things down.

Essays from the people who build Folio: how teams keep a handbook true, how we write specs, and what we learned teaching an assistant to show its sources.

MEdited by Marta6 postsNew every other week

Latest · Teams

The handbook nobody reads, and the one everybody does.

Larchmont deleted 340 stale pages in a month and people started trusting the handbook again. Here is the audit behind it, step by step.

KKofi Mensah7 min read

Read the post

The archive

Read by topic.

5 posts

  • Product6 min

    Why Ask Folio shows its sources first.

    An answer you cannot check is a rumour. How we designed Ask Folio around the lines it read, and why it sometimes says it couldn’t find anything.

    LLea Moreau

  • Engineering9 min

    Fifty thousand rows in under a second.

    How we made databases open four times faster without a rewrite: a smaller first paint, a smarter query plan and one very boring cache.

    HHana Sato

  • Inside Folio5 min

    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.

    JJonas Brandt

  • 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

  • Ask Foliofrom 6 posts

    “I just became a team lead. What should I read first?”

    1. Start with the handbook audit: it takes thirty minutes and fixes the pages people act on. 1
    2. Then the meeting notes habits, so decisions get one owner and one date. 2

The Folio Dispatch

One email a month, worth opening.

One email on the first Tuesday of the month: what shipped, and one template worth stealing.

From Marta at Folio

Subject Issue 38: the 30-minute handbook audit

11,000 readers. Unsubscribe in one click.

Write your own handbook this afternoon.

Start from the templates in these posts, or from a blank page that already knows what a heading is.