What It Is
A documentation system combines tools, writing norms and maintenance responsibilities.
Inference — synthesis of the documented company cases below, not a comparative study of every distributed company. Useful features to assess include a canonical place for each type of content, timely decision records, named maintainers and context for future readers. Tool choice alone does not establish these practices.
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.]
Records can support later work. Inference: a maintained handbook can preserve useful context across teams and employee changes. This is the rationale behind the cited operating accounts, not a measured improvement in organizational intelligence. (GitLab guidance)
Writing can replace some coordination. 37signals describes written decisions and asynchronous updates as defaults alongside occasional live calls. Inference: use documentation where it answers the question; it does not eliminate every need for a meeting. (Source)
Automattic uses P2 alongside other project tools. Project discussions on P2 create persistent written records, while the company also lists Linear, private chat rooms and Slack. [Inference — application guidance.] Preserve decisions across that toolset rather than assuming every piece of project work lives in one blog system. (Source)
Zapier encourages working in public. Shared channels and written context help colleagues find information without waiting for an immediate reply. This is a communication norm, not evidence that every artifact is visible to everyone. (Source)
Where It Fails
Documentation needs maintenance. GitLab treats documentation as part of work. Inference: stale guidance can mislead people, so important records need ownership and review. The reviewed cases do not show what most companies do. (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 — Handbook as an operating reference. GitLab describes a handbook-first communication model. Inference: public documentation makes the operating account inspectable; it does not prove that external readership causes quality. (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 among project tools. How We Work lists P2 alongside Linear, private chat rooms and Slack. Inference: preserve durable decision context across this toolset rather than assuming one system holds all work. The reviewed sources do not establish a historical 70%/150-site split. (Source)
Zapier — Working in Public. Zapier encourages shared channels and written context so other people can find and reuse the work. The reviewed primary does not establish a mandatory single-page specification for every project. (Source)
Todoist (formerly Doist) — Public Handbook and Structured Onboarding. Todoist publishes a public handbook with onboarding and people-practice material. Some linked internal documents remain unavailable publicly. (Handbook)
Shopify — Evidence That Travels With a Handoff. Its September 2026 River account describes preserving the investigation for the engineer who must decide, and checking the recorded outcome after a fix ships. [Inference — application guidance.] Documentation should carry the decision context through the workflow. (Source)
Implementation Guide
Inference — application guidance drawn from the cited company cases, not measured rules or guaranteed outcomes.
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
Inference — application guidance drawn from the cited company cases, not measured rules or guaranteed outcomes.
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.
Related Frameworks
- Sync vs Async Decision Matrix — choose a communication mode for the work
- The 20–30 Person Fracture Point — a working hypothesis about coordination needs during growth
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
Todoist public handbook (accessed September 2026): https://www.todoist.com/handbook
Shopify — River security remediation (September 2, 2026): https://shopify.engineering/river-vulnerability-remediation
Inferences
- Public handbooks make a company’s operating account inspectable. This does not establish that private handbooks have lower quality.
- Automattic’s project discussions and 37signals’ context-specific records illustrate ways to keep documentation close to the work. Separate maintenance can still be necessary.
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.