---
title: "Why we write system docs in plain language (and how)"
description: "The people who run the system aren't the people who built it. A documentation template, a worked example, and the pushback we get for refusing to use jargon."
slug: "plain-language-systems"
date: "2026-03-19"
updated: "2026-03-19"
author: "Nick Barnard"
authorAvatar: "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?q=80&w=200&auto=format&fit=crop"
image: "https://images.unsplash.com/photo-1454165804606-c3d57bc86b40?q=80&w=2000&auto=format&fit=crop"
category: "Process"
tags:
  - Documentation
  - Plain language
  - Operations
  - Handoff
primaryKeyword: "plain language system documentation"
secondaryKeywords:
  - "internal docs without jargon"
  - "runbook plain English"
  - "system documentation template"
canonicalUrl: "https://tolly.ai/blog/plain-language-systems"
markdownUrl: "https://tolly.ai/blog/plain-language-systems.md"
featured: false
published: true
---

Plain-language documentation isn't dumbing things down — it's writing for the actual reader. The actual reader, six months after launch, is rarely the engineer who built the system. It's the operations lead who needs to know why the cron is paged, the new hire who needs to understand the qualifier rubric, or the founder who needs to explain to a customer what just happened. Jargon optimizes for the writer's comfort. Plain language optimizes for the reader's job.

## The cost of jargon

Most internal documentation gets written in two modes: the engineer who built the thing tries to sound rigorous, or the engineer who built the thing tries to sound brief. Both produce docs that are unreadable to the people who'll need them most.

Concrete cost we've seen: a team of 12 spent four months unable to fix a production bug because the only documentation was a sequence diagram drawn by an engineer who'd left. The bug was a one-line config change. The four months were *finding* the line.

## A documentation template that works

For every system we ship, we write four documents. Each has a strict structure and a length limit. Anyone on the customer's team should be able to read all four in under 30 minutes.

### 1. The What (one page)

What does this system do, in plain English, told to a teammate at lunch?

- One paragraph: the workflow this replaces.
- One paragraph: what changes for the team day-to-day.
- One paragraph: what the system *won't* do (the edges).

No system architecture. No code. No pseudocode.

### 2. The When (one page)

When does it run? When does it stop? When does it page someone?

- The schedule (cron, event-triggered, manual).
- The conditions for skipping (e.g., "skips weekends", "skips for VIP accounts").
- The conditions for paging on-call (e.g., "if the queue depth exceeds 50, alerts the #ops Slack channel").

A flowchart only if it makes the trigger conditions clearer. Most don't.

### 3. The How-it-broke (the runbook, two pages max)

For every realistic failure, a section with three things:

- What it looks like (the symptom your team will see).
- The likely root cause.
- The exact commands or clicks to recover.

We write the recovery instructions for someone who has never seen the system. If they need to know what `bun run drain-queue` means, the doc explains.

### 4. The Why (one page)

The decisions we made and the alternatives we rejected. This is the document that keeps your team from rebuilding the same wrong version in two years.

- What we considered.
- Why we picked what we picked.
- Under what conditions we'd revisit the decision.

This is the most-skipped doc in the industry, and the one that pays off most over time.

## A worked example

Here's the real "What" doc from a recent lead-qualification system, lightly edited for anonymity:

> ### What this does
>
> When a new lead comes in through the website form, this system reads it, decides whether it matches our ideal-customer profile, and either drafts a personalized email for sales to send, or files the lead under "low priority" with a one-line note about why.
>
> Today this happens on Tuesday afternoons by hand. After launch, it'll happen within 90 seconds of the form submission. Sales sees the drafted email in Slack and either sends it as-is, edits it, or rejects it. Nothing auto-sends without a human click.
>
> ### What it won't do
>
> It won't decide *whether* a lead is qualified — it scores them against the rubric we agreed on, and the rubric is the source of truth. If the rubric is wrong, the system will be wrong in a predictable, fixable way.
>
> It won't reach out to existing customers. Inbound forms from known emails are routed to your account manager, not the qualifier.
>
> It won't write personalized emails for leads that score below 40. Those go to the "low priority" file with a note. If you want the system to draft something for those, that's a config change, not a rebuild.

That's the entire doc. No engineer needed to read it. No operations lead needed to ask follow-up questions. It went into the customer's Notion next to their existing process docs and was used in onboarding for the next three new hires.

## Common pushback we hear

| Objection | Our answer |
| --- | --- |
| "Plain language doesn't capture the complexity" | If the complexity matters for operating the system, we explain it without jargon. If it doesn't, the doc doesn't need it. |
| "We need precise technical terms" | The runbook can use them. The "What" cannot. Different docs, different audiences. |
| "Engineers find plain English condescending" | Engineers aren't the audience for these docs. The handoff to operations is the audience. |
| "This will take longer to write" | It does. About 25% longer. The payoff is months of operational time saved across the system's life. |

## Frequently asked questions

### Do you use AI to write these docs?

We use it for first drafts, then heavily edit. AI is good at structure and bad at knowing what your team actually needs to know. The voice matters — these docs get read by humans, repeatedly, often under stress.

### How do you handle code-level documentation?

Inline comments only when the *why* isn't obvious. We don't write JSDoc on every function. Code that needs prose explanation usually wants to be refactored, not annotated.

### What if the customer doesn't read them?

Most don't, until something breaks. That's fine. The point of the runbook is that it's *there* when someone needs it at 11 PM, not that everyone read it on launch day.

## The takeaway

Plain-language documentation isn't a writing style — it's a discipline about who the reader is. Write the four docs. Set the length limits. Refuse to ship a system without them. Your future team, including the people you haven't hired yet, will be able to operate what you built. That's the thing that actually reduces vendor lock-in: not the contract, not the architecture, but the docs that let any competent engineer understand the system in 30 minutes.