Skip to content

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.

IEdited by InesSep 17, 20266 min read

Every page in your workspace has two readers. The first is a colleague this week, who has context and can ask you if something is unclear. The second joins in a year. You will have changed teams, the Slack thread will be gone, and the page is all they have.

The reader who can’t ask

Write for the second reader and the first one is fine too. Spell out the acronym once. Link the page you are referring to instead of saying “the doc from last week”. Say which team, which customer, which quarter.

Keep the why

Decisions age badly on their own. “We don’t use feature flags for pricing changes” looks arbitrary in a year. “We don’t use feature flags for pricing changes, because in 2024 a flag showed two prices to the same customer” is a rule someone can keep, or change on purpose.

A rule without a reason gets broken by the first person who is in a hurry. A reason gets argued with, which is better.
From our own handbook, “How we write”

Leave a date

A page that says when it was last true tells the reader how much to trust it. That is why Folio pages carry an owner and a Verified until date, and why Ask Folio prefers verified pages when two pages disagree. A date is not bureaucracy. It is a kindness to someone you will never meet.

  • Name the owner of the page at the top.
  • Date the decisions, not just the page.
  • When something changes, strike it through and add the new line, instead of deleting the old one.

We built Folio because we kept being the second reader. If your team keeps being them too, start with a good page.

I

Written by

Ines Duarte

Co-founder, CEO, Lisbon. Owns the page “Company handbook”.

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

  • 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

Write it down once. Find it forever.

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