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.
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.