Field Guide

At any given moment, a senior engineer at Squarespace was asked to know four things that lived in four different wikis.

The design system docs were in one place. The platform runbooks were in another. The front-end onboarding guide was a Notion table, and the backend architecture tour was a Google Doc that had been copy-pasted so many times the headings didn't match anymore. Each had a maintainer; none had the same maintainer; every one of them described the same company from a slightly different angle.

The real problem wasn't that the content was bad. It was that the system didn't behave like a system. You couldn't link between wikis without breaking. You couldn't search across them. You couldn't know, when you read a page, whether it had been touched in the last six months or the last six years. The reader's question was always the same — can I trust this? — and the answer was always different.

I was given six months and a team of three. The brief was a one-pager: consolidate the four surfaces, keep people writing, don't build another wiki. That last clause did the most work. The worst thing we could do was ship something that felt like the old thing with a new coat of paint; people would keep using the old thing and we'd have spent six months building a fifth wiki.

We settled on a constraint that looked small and cost a lot: every page is an entry. No folders, no hierarchy, no "architecture vs. runbook vs. onboarding" distinction at the file level. If you wrote something, it was an entry. Entries carried tags. Tags composed into views. The reader could browse by shape of question rather than by which team had authored the answer.

// entry-schema.ts — the shape that made the whole thing work
type Entry = {
  id: string;
  title: string;
  body: Markdown;
  tags: Tag[];
  updatedBy: User;
  updatedAt: Timestamp;
  /* the last field is the one every wiki forgot: */
  confidenceDecaysAt: Timestamp;
};

The visual language borrowed from naturalists' field notebooks: a central composition, wide margins, small diagrams set into the prose, the author's initials in the lower right of each entry. None of this was decorative. The margins were where comments lived. The diagrams were inline because putting them at the end turned them into appendices no one read. The initials meant you always knew whose trust you were extending when you followed a link.

We made one hard rule at the typography level: prose first. If the thing you were writing couldn't be read out loud, it probably wasn't an entry yet — it was notes toward one. The writer's cursor sat in a 62ch column. Everything else — diagrams, tables, code — had to earn its way out.

Field Guide shipped in March 2024. As of the last count, it has collected 2,412 entries across 14 product teams. We archived the four old wikis by mid-June and haven't had to argue about it since. The teams that complained the loudest at kickoff are the ones writing the most now; the inverse is almost always true.

The part I'm most proud of isn't the interface. It's the decay column. Every entry has to declare when its author expects it to stop being true. Six months from now, three years, never. When the date lapses, the entry isn't deleted — it's dimmed. The reader sees the prose through a soft scrim and a note at the top: this entry's author expected it to go stale by now. Trust stops being an assumption and starts being a surface you can see.