What It Is
A documentation system is the combination of: (1) the tools where written knowledge is stored, (2) the norms that govern what gets documented and how, and (3) the culture that treats documentation as real work rather than overhead.
The tool is the least important part. A company with great documentation norms will produce useful knowledge in Notion, Confluence, GitHub READMEs, or a custom wiki. A company with poor documentation norms will produce scattered, stale, contradictory documentation in any tool.
The best remote-company documentation systems share several characteristics:
- Single source of truth — one canonical place for each type of content
- Written at the moment of decision — not reconstructed after the fact
- Maintained by owners — documents have named maintainers who are accountable for accuracy
- Structured for future readers — written for someone who was not there and has no context
Why It Works
Documentation is the mechanism for organizational memory that does not depend on people staying. When a key engineer leaves a colocated company, their knowledge partially transfers through hallway conversations and informal relationships before they go. When they leave a remote company, they take their knowledge with them unless it was written down. Documentation is the structural insurance policy against knowledge loss. [Inference — central argument; consistent with what GitLab and 37signals codify in their handbook-first stance but not measured cross-company.]
Documentation creates compounding organizational intelligence. Every decision written down is available to future employees, future teams, and future product cycles. GitLab’s handbook has been growing and improving for 10+ years — it is a compounded representation of the company’s hard-won operational knowledge. (Source)
Documentation replaces the meeting. When a question is answerable by a document, it does not need a meeting. 37signals’ rule: “if it’s important, critical, or fundamental, write it up, don’t chat it down.” (Source) The more documented the operating system, the fewer meetings are necessary.
Automattic’s P2 system creates permanent project documentation as a byproduct. Because all project work happens on P2 blogs — threaded, searchable, persistent — the documentation does not require a separate “documentation phase.” The work and the record of the work are the same thing. (Source)
Zapier’s “default to transparency” makes documentation the default, not the exception. When all work is done publicly — in shared channels rather than DMs — the artifact of the work (the thread, the issue, the document) is visible to the whole company. The documentation norm is enforced by the transparency norm. (Source)
Where It Fails
Documentation without maintenance becomes misinformation. A handbook with 2,000 pages and 500 stale entries is actively harmful — it gives people wrong answers confidently. GitLab explicitly assigns document owners and treats handbook maintenance as real work. Most companies do not. (Source)
The tool becomes the goal. “We are moving to Notion” is not a documentation initiative — it is a tool migration. Tool migrations without changes to writing norms and maintenance responsibilities produce the same documentation quality in a different tool. [Inference — practitioner observation; not a measured pattern but a known failure mode in documentation-tool migrations.]
Documentation as bureaucracy, not infrastructure. When documentation is required for compliance rather than utility, people write documents that satisfy the requirement without transferring knowledge. “Bureaucratic documentation” — process docs that nobody reads, specs that are out of date by launch — is worse than no documentation because it creates false confidence. [Inference — practitioner observation; the failure mode is consistent with what GitLab’s “documentation as real work” framing is designed to counteract.]
Nobody reads docs that are hard to find. The quality of the documentation is irrelevant if the information architecture is broken. “The right communication in the wrong place might as well not exist at all.” — 37signals. (Source)
Best Examples
GitLab — 2,000-Page Public Handbook as Operating System. The GitLab Handbook is the single source of truth for the entire company. It covers everything: values, processes, team structures, performance management, engineering practices, communication norms. It is public — which creates external accountability for the quality of what is written. It is maintained by document owners who treat updating it as real work. The handbook is not a product of documentation culture — it is the documentation culture made visible. (Source)
37signals / Basecamp — Basecamp as the Single Canonical Tool. The vast majority of internal communication happens inside Basecamp — 37signals’s published guide describes Basecamp as where “98% of communication” lives. Everything important lives there: decisions, project documentation, check-ins, heartbeats, kickoffs. “A single centralized tool keeps everything together and creates a single source of truth for everyone across the company.” Spatial context is enforced: discussions are attached to the thing they are about, not separated into a general chat. (Source)
Automattic — P2 Blogs as Project Documentation Infrastructure.
The current Automattic “How We Work” page describes that “in addition to Linear, we track our projects on P2-themed WordPress.com blogs, in private chat rooms, and on Slack.” Earlier writings put the share of work happening on P2s at around 70% across more than 150 P2 sites; the company has not published an updated breakdown, so the specific percentage is treated as historical estimate, not current published number — see the parallel hedging on /companies/automattic. The blog format creates permanent, searchable, threaded records of project discussions and decisions. Unlike chat tools where conversations scroll away, P2 posts are permanent artifacts. (Sources, expectations)
Zapier — Single-Page Specs + Public-by-Default. Every significant project starts with a single-page spec documenting goals, success criteria, key decisions, and the DRI. By working in public by default (shared channels over DMs), the process of doing work produces its documentation. Slack threads link to GitHub issues link to Quip docs — creating traceable information trails that persist beyond the conversation. (Source)
Implementation Guide
1. Decide what belongs where. Decisions → handbook or decision log. Process documentation → handbook. Project work → project tool. Casual discussion → chat. The information architecture must be defined before it can be followed.
2. Assign document owners. Every important document has one named person responsible for its accuracy. No owner = no maintenance. No maintenance = stale information.
3. Write at the moment of decision. The highest-quality documentation happens when the decision is fresh. “Retrospective documentation” — writing up how something was decided three months later — is lower quality and often never happens. The habit to build: write the decision into the document before closing the meeting or the thread.
4. Write for the future reader. Every important document should be comprehensible to someone reading it a year later with no context. Assume no shared knowledge. This discipline produces documents that are actually useful.
5. Make updating docs as easy as creating them. If your documentation tool requires a 6-step process to update a line of text, people will not update it. The tooling should make small updates as frictionless as possible.
6. Include documentation work in performance expectations. If documentation is not rewarded — if people are evaluated purely on shipping — then documentation is always the thing that gets cut under pressure. Make it an explicit expectation.
Common Mistakes
Creating a wiki and calling it a documentation system. A wiki is a tool. A documentation system is a tool plus norms plus culture plus maintenance processes. The wiki is the least important part.
Documenting everything. Not everything should be documented at the same level of formality. A small decision that only affects one person for one week does not need a handbook entry. Reserve formal documentation for durable, important, or frequently-needed information. Over-documenting creates the same problem as under-documenting: key information is buried in noise.
Documentation-then-forget. Writing a process document once and never reviewing it is worse than not writing it. When the process changes and the document does not, the document becomes actively misleading. Review important documents at least annually.
Treating documentation as a solo activity. The best documentation is reviewed by people who were not there. The document owner should ask: “Would someone who doesn’t know this context understand what I’ve written?” If not, the document is not done.
Sources
- GitLab Communication Handbook: https://handbook.gitlab.com/handbook/communication
- The 37signals Guide to Internal Communication: https://basecamp.com/guides/how-we-communicate
- How We Work — Automattic: https://automattic.com/how-we-work/
- Expectations — Automattic: https://automattic.com/expectations/
- How to Work Asynchronously — Zapier: https://zapier.com/blog/how-to-work-asynchronously
Inferences
- GitLab’s public handbook is not just an operational tool — it is a cultural artifact that demonstrates the company’s values to the market. When documentation is public, the quality of what you write says something about how you think. Companies that keep their handbooks internal lose this accountability mechanism. The external readership is not incidental to the handbook’s quality.
- The documentation systems of the best distributed companies are all built on the same underlying principle: the record of the work and the work are the same thing. When you have to do a separate “documentation phase” to capture what happened, documentation competes with work and usually loses. Automattic’s P2 system and Basecamp’s spatial-context rule both collapse this distinction — the work produces its own documentation as a byproduct.
Work with Alex
If your company’s institutional knowledge lives in people’s heads and Slack threads that will disappear, Alex helps leadership teams build the documentation infrastructure that makes your operating system durable.