Technical Writing and Documentation Questions

Direct answer

I would judge documentation by what happens after someone reads it: do they find what they need, act on it, and stop asking people? So I collect a few behavioural signals (search that fails, questions that repeat, ramp time for new hires), one or two opinion signals (a page rating and a short survey), and I would distrust raw page views, which go up when docs are good and also when they are confusing.

Signals and how to collect them

MTTR by runbook tag, with made-up numbers: incidents with a runbook took 45, 30 and 60 minutes (mean 135/3 = 45); incidents without one took 90, 120 and 75 (mean 285/3 = 95). The 50-minute gap is a hint, not proof, since the incident types may differ.

Worked example (illustrative data, run it)

# Tiny, made-up docs-effectiveness data (illustrative). Each row is one week.
weeks = [
    # (page_views, searches, searches_with_no_click, tickets, tickets_where_answer_was_in_docs)
    (900, 200, 90, 40, 14),
    (1500, 210, 60, 33, 9),   # after rewriting the top pages
]
for i, (views, searches, no_click, tickets, in_docs) in enumerate(weeks, start=1):
    print(f"week {i}: views={views}",
          f"| search abandonment={no_click / searches:.0%}",
          f"| avoidable tickets={in_docs / tickets:.0%} ({in_docs}/{tickets})")

# Onboarding signal: days from start date to first merged pull request
before = sorted([21, 24, 19, 30, 26])
after = sorted([14, 16, 12, 20, 15])
median = lambda xs: xs[len(xs) // 2]
print("median days to first merged PR:", median(before), "->", median(after))

Output:

week 1: views=900 | search abandonment=45% | avoidable tickets=35% (14/40)
week 2: views=1500 | search abandonment=29% | avoidable tickets=27% (9/33)
median days to first merged PR: 24 -> 15

Reading it: after rewriting the top pages, search abandonment fell from 45% (90 of 200 searches) to 29% (60 of 210), avoidable tickets from 35% (14 of 40) to 27% (9 of 33), and the median time to first merged PR from 24 to 15 days. Note that page views rose too; on their own, views could not have told us whether that was good.

Which popular measure I distrust: page views

Views measure traffic, not usefulness. A confusing page produces repeat visits and more views. A great page that answers in one glance also produces views but no follow-up. Other gameable ones are "number of pages written" and "words". Guard by pairing every activity measure with an outcome measure (views with search abandonment; docs written with avoidable tickets).

Quantitative versus qualitative KPIs (key performance indicators, the few numbers you track to judge success) and the response when one drops

Quantitative: the rates above. Qualitative: free-text feedback, and watching a new hire try a task. When a KPI drops, look at the pages contributing most, read the comments, run a 20-minute test with someone who has not seen the page, then fix and re-measure a few weeks later. Also link the improvement to an outcome such as incident time to resolve: compare incidents where the runbook was used with those where it was not.

Pitfalls

Small samples (say which counts are behind a percentage), changing two things at once, and treating a correlation as proof. Say the numbers back a claim about direction, not exact cause.

Direct answer. Before an engineering document (a design doc, runbook or API guide) is marked "final", I run a short checklist and split it into hard gates (the document cannot be marked final while any fail, and a named person signs off) and advice (good practice, author's judgement).

Terms. A design doc explains how something will be built and why. A runbook is step-by-step instructions for handling a task or alert. A changelog is a dated list of what changed. A staging host is a practice copy of production where steps can be tried safely. An architecture board is the group that approves significant technical designs. Internal-only hostnames are server names that only resolve inside the company network and reveal how it is laid out.

Hard gates, with sign-off

Advice (not gates)

• Consistent terminology, and acronyms defined on first use.
• Diagrams have text alternatives and readable labels.
• Length trimmed, headings scannable, examples included.
• Changelog entry describing what changed.

Worked example. A runbook for a failing job: the author lists "restart the worker with systemctl restart worker". The reviewer runs it on a staging host and finds it needs sudo. That is an accuracy gate finding, so the document stays "draft" until fixed and re-tested, but the missing changelog line is only advice and does not block.

Worked example: the security and approval gates. The security reviewer runs a scan over the public draft for credentials and internal hostnames. On a draft runbook containing SSH to db01.corp.internal and export API_KEY=AKIAABCDEFGHIJKLMNOP (AKIA-prefixed strings look like cloud access key IDs), this command:

grep -nEi "AKIA[0-9A-Z]{16}|password|\.corp\.internal|(^|[^0-9])10\.[0-9]+\.[0-9]+\.[0-9]+" runbook.md

prints lines 2 and 3 and exits 0. The draft runbook.md is three lines: line 1 # Runbook: database failover, line 2 SSH to db01.corp.internal, line 3 export API_KEY=AKIAABCDEFGHIJKLMNOP; the fixed draft keeps line 1 and has SSH to <db-host> and export API_KEY=<from secrets manager> on lines 2 and 3. The first match means the gate fails. After the author replaces them with <db-host> and <from secrets manager>, the same command prints nothing and exits 1 (no match, gate passes). I ran both. The scan catches only patterns you thought of, so the reviewer still reads the doc. For the approvals gate, a public doc is not final until the document carries a line such as Approved: <name>, architecture board, 2026-09-14 (link to ticket), written by the approver, which is what makes a signature traceable later.

Why split it this way. If everything is a gate, people rubber-stamp; if nothing is, "final" means nothing. Gates are the items where being wrong causes harm (a broken procedure at 3am, a leaked secret).

Direct answer

I split it by what the reader is trying to do when they arrive, not by the headings the original author chose. A reader in the middle of a task wants steps, a reader looking something up wants exact values, and a reader trying to understand wants reasons. Those three needs conflict on one page, so I separate them and link them. This is the idea behind the Diataxis documentation framework, which names four kinds of page: tutorial, how-to guide, reference and explanation.

How I decide where to cut

1. Inventory: paste the page into a spreadsheet, one row per paragraph, table or list.
2. Label each row by the question it answers:
   • "How do I do X?" is a how-to guide.
   • "What is the exact value or option?" is reference.
   • "Why is it this way, and what else could we have done?" is explanation.
   • "Teach me from zero by doing" is a tutorial (only if a beginner audience exists).
3. Cut where the label changes and keep short pointers (one sentence "why", with a link) in place, so how-to readers are not stranded.
4. Keep the old URL as a small hub linking to the new pages, because bookmarks and other pages point to it.

What each resulting page owes its reader

Worked example (illustrative)

Inherited page "Payments queue" with 9 blocks: (1) 6 numbered steps to replay a dead-letter queue (a holding queue for messages that failed), (2) a table of 14 config settings, (3) a paragraph on why the team chose at-least-once delivery (a message may arrive more than once but is never lost), (4) a table of error codes, (5) steps to add a new consumer, (6) history of a 2023 migration, (7) a table of queue names per environment, (8) a paragraph on retry design, (9) a checklist for adding a new queue.

Labels: how-to = blocks 1, 5, 9 (3 blocks); reference = blocks 2, 4, 7 (3 blocks); explanation = blocks 3, 6, 8 (3 blocks). Result: three pages of three blocks each, plus the old URL as a hub.

Trade-offs and pitfalls

• Over-splitting: a three-line rationale does not deserve its own page. Keep a sentence inside the how-to and link out when the reason is long.
• Splitting by heading instead of reader need, which reproduces the same tangle.
• Duplicated facts across pages: state a value once (in reference) and link to it.
• Do it in one reviewed change, with the owner of the system approving the labels, and ask a real user which page they would open for a given task.

Direct answer

Write one document that works for three readers by leading with the conclusion, using one word for one thing, and making every sentence concrete: a named actor, a number, a unit. Engineers want checkable claims, product managers want the decision and its impact, and lawyers want commitments that cannot be read two ways. Plain, exact sentences serve all three.

Rules of thumb

1. Put the conclusion first. The first two sentences say what happened, what is decided, or what is asked. Detail follows for those who need it.
2. One term, one meaning. Define a term once, then never swap in a synonym. If "customer" means the paying company, do not later use "user" for the same thing. Lawyers read a change of word as a change of meaning.
3. Name the actor and use active voice. "The service deletes the file" says who does what. "The file will be deleted" hides who.
4. Use numbers, units and dates, not adjectives. "Fast", "soon" and "a short period" cannot be checked.
5. One idea per sentence, and short. It survives translation and skimming.
6. Separate facts, opinions and commitments. Label recommendations as recommendations. Use "must" for a requirement, "should" for a recommendation and "may" for a permission, the convention of RFC 2119 (an internet standard whose keywords are MUST, SHOULD and MAY, written in capitals in the standard itself). Avoid "can" for permission, since it can also mean ability.
7. Say what you do not know. "We have not tested above 500 requests per second" is more trustworthy than silence.
8. Expand acronyms on first use and keep a glossary.

One rule applied to a real sentence (rule 3 plus rule 4)

Before:

Customer data may be retained for a period following termination as deemed appropriate and will be handled in accordance with policy.

After (example figures, to be confirmed with the owner):

We delete customer data 30 days after the contract ends. We delete backups within 90 days after that.

What changed and why each reader benefits:

Trade-offs and pitfalls

• Precision creates commitments. "We delete" is a promise, so do not publish a number until the owning team and legal have confirmed it. If the true answer is "it depends", write the dependency: "We delete data 30 days after the contract ends unless a legal hold applies."
• Do not hide behind qualifiers to stay safe ("generally", "in most cases"). Either state the exception or drop the hedge.
• Layer the document: a short summary on top for the PM and the lawyer, detail below for the engineer, rather than three separate versions that drift apart.
• Have a person from each group read the draft for one thing only: the sentence they would act on. Their confusion shows where the text is weak.

Direct answer. All three are documents, but they answer different questions. A README answers "what is this and how do I start?", a runbook answers "what exact steps do I follow for this task or alert?", and a playbook answers "how do we handle this kind of situation, and who decides what?". Naming conventions differ between companies, so I state my definitions when I write one. In everyday terms: a runbook is an operating instruction sheet, like a recipe you follow exactly; a playbook is a team's game plan, which tells people their roles and when to make a call; a README is the front-door sign of a project.

Worked example: a payments service.

• README: "Payments API. Requires Python 3.12. Run make dev. Tests: make test. Docs: link."
• Runbook: "Alert: queue depth above threshold. 1. Check the consumer dashboard. 2. Run kubectl rollout restart deployment/payments-consumer. 3. Confirm the queue drains within 10 minutes. 4. If not, roll back to the previous release (command)." Each step is unambiguous and checkable.
• Playbook: "Suspected payment data leak. Incident commander declares severity. Security lead assesses scope. Legal decides on notification. Communications drafts customer message. Decision point: take the service offline? criteria listed." It links to the runbooks for isolating a host.

Choosing between them. If the reader must think, it is a playbook; if the reader must follow, it is a runbook; if the reader is arriving cold, it is a README. A typical mistake is writing a runbook full of judgement calls (it fails at 3am) or a playbook full of shell commands (it goes stale quickly).