How to Write Technical Documentation in English at Work
ESL English learning: Master the vocabulary and phrases for writing design docs, RFCs, postmortems, and other technical documentation in English.
Pronunciation Guide for Documentation Terms
Some technical documentation terms are commonly mispronounced. Here's a guide to help you sound confident in meetings and reviews.
postmortem /poʊstˈmɔːrtəm/
Stress on MOR; literally 'after death' from Latin
iterate /ˈɪtəreɪt/
Stress on first syllable: IT-er-ate
mnemonic /nɪˈmɒnɪk/
Silent 'm' at the start; used for memory tricks like acronyms
cache /kæʃ/
Sounds like 'cash,' not 'catch' or 'kaysh'
schema /ˈskiːmə/
Sounds like 'SKEE-muh'
queue /kjuː/
Sounds exactly like the letter 'Q'
Memory Trick: Mnemonics for Tech Writing
A mnemonic is a memory aid. For example, to remember design doc sections: CPTAR = Context, Problem, Trade-offs, Alternatives, Recommendation. Creating mnemonics for your team's document templates can help everyone stay consistent.
Types of Technical Documents You'll Write
Just as academics write different types of papers for different purposes, tech professionals produce various document types. Knowing the right term signals professionalism and helps your team understand the scope and formality of what you're sharing.
| Term | Meaning | Example |
|---|---|---|
| README | Quick-start guide for a repo or tool; helps new users get oriented | 50–500 words |
| One-pager | Brief proposal or summary to get alignment before deeper work | 1 page / 300–600 words |
| Spec (specification) | Detailed requirements for a feature or system; often handed to implementers | 1,000–3,000 words |
| Spike | Time-boxed investigation to reduce uncertainty; documents findings and recommendations | 500–1,500 words |
| Design doc | Proposes a technical approach, explains trade-offs, and invites feedback | 2,000–5,000 words |
| RFC (Request for Comments) | Formal proposal for cross-team or org-wide review; similar to design doc but broader scope | 2,000–6,000 words |
| ADR (Architecture Decision Record) | Records a specific architectural decision and its rationale for future reference | 300–800 words |
| Runbook | Step-by-step guide for operating or troubleshooting a system | 500–2,000 words |
| Postmortem | Analysis of an incident: what happened, why, and how to prevent recurrence | 1,000–3,000 words |
Spec vs. Spike vs. One-Pager
A spec says what to build with detailed requirements. A spike is an investigation to figure out if something is feasible. A one-pager is a lightweight summary to get buy-in before investing more time. Use the right term so stakeholders know what to expect.
Documentation Process Vocabulary
Writing technical documents involves a clear workflow. Understanding process vocabulary helps you communicate status and next steps to your team.
| Term | Meaning | Example |
|---|---|---|
| draft (n. / v.) | An early version of a document; to write an early version | I'm still drafting the design doc—it's not ready for review yet. |
| iterate (v.) | To revise and improve through multiple cycles | Let's iterate on the proposal after we get initial feedback. |
| circulate (v.) | To share a document with stakeholders for input | I'll circulate the RFC to the platform team tomorrow. |
| submit (v.) | To formally hand in a document for review or approval | Please submit your design doc by Friday EOD. |
| deadline (n.) | The date by which something must be completed | The deadline for ADR comments is next Wednesday. |
| feedback (n.) | Comments and suggestions from reviewers | I incorporated all the feedback from the security review. |
| sign off (v. / n.) | To formally approve; formal approval | We need sign-off from the tech lead before implementation. |
| ship (v.) | To finalize and publish (informal) | Let's ship this runbook so the on-call team can use it. |
Process Terms in Context
- Could you draft the postmortem and circulate it by Thursday?
- We've iterated on the design doc three times based on reviewer feedback.
- Once the tech lead signs off, we can submit the RFC to the architecture review board.
- The deadline for the spec is tight, so I'm going to ship a first draft today and improve it later.
Formal vs. Informal Register: Slack vs. Design Docs
Tech culture often blends casual communication (Slack, standups) with formal documentation. Knowing when to shift register is essential. A design doc requires a more formal tone than a quick Slack message, even if you're saying similar things.
| Term | Meaning | Example |
|---|---|---|
| Proposing an idea | I think we should try X | This document proposes X as the recommended approach |
| Acknowledging uncertainty | Not 100% sure yet | This area requires further investigation |
| Asking for feedback | LMK what you think | Feedback is welcome, particularly on sections 3 and 4 |
| Describing a problem | This thing keeps breaking | The current implementation exhibits intermittent failures |
| Stating a limitation | We can't do Y | Y is out of scope for this proposal |
| Referencing sources | Saw it in that doc somewhere | As documented in [link], the system currently... |
When to Use Which Register
Use informal register in Slack, quick syncs, and internal team chat. Switch to formal register for design docs, RFCs, postmortems, and any document that might be read by people outside your immediate team or referenced months later.
Common Mistakes: Heard-at-Work vs. Better English
Non-native speakers often make subtle errors that can confuse readers or sound unprofessional. Here are common mistakes heard in tech workplaces and how to fix them.
| Term | Meaning | Example |
|---|---|---|
| I will make a research on this | I will research this / I will investigate this | 'Research' is a verb; no need for 'make a' |
| Please give me a feedback | Please give me feedback / Please share your feedback | 'Feedback' is uncountable—no 'a' |
| We need to discuss about the trade-offs | We need to discuss the trade-offs | 'Discuss' doesn't take 'about' |
| I already submitted the document yesterday | I submitted the document yesterday | 'Already' is often unnecessary with past tense + time marker |
| According to me, we should use Kafka | In my view / I believe we should use Kafka | 'According to me' sounds unnatural |
| The deadline is until Friday | The deadline is Friday / The deadline is by Friday | 'Until' doesn't work with deadlines |
| I will revert back to you | I will get back to you / I will follow up | 'Revert' means return to a previous state (like git revert) |
Fix the errors in these sentences from technical documents.
Fill in the blank
Please give me a feedback on the design doc by EOD.
Fill in the blank
We need to discuss about the migration strategy in the RFC.
Fill in the blank
According to me, Option B is the better approach.
Scenario: Drafting a Postmortem After an Incident
Postmortems (also called incident retrospectives or post-incident reviews) are critical documents that analyze what went wrong and how to prevent recurrence. They require precise, blameless language.
| Term | Meaning |
|---|---|
| root cause | The fundamental reason the incident occurred |
| contributing factor | A condition that made the incident worse or more likely |
| blast radius | The scope of impact—how many users/systems were affected |
| time to detection (TTD) | How long before the team noticed the problem |
| time to resolution (TTR) | How long to fix the issue once detected |
| action item | A specific task to prevent recurrence |
| blameless | Focusing on systems and processes, not individual fault |
Postmortem Phrases in Context
- The root cause was a misconfigured load balancer that failed to route traffic correctly.
- A contributing factor was the lack of automated alerting for this failure mode.
- The blast radius was limited to 5% of users in the EU region.
- Time to detection was 23 minutes; time to resolution was 47 minutes.
- Action item: Add integration tests to catch configuration drift before deployment.
- This postmortem is blameless—we focus on systemic improvements, not individual errors.
Cultural Note: Blameless Culture
In healthy engineering cultures, postmortems avoid blaming individuals. Instead of writing 'John deployed bad code,' write 'The deployment process did not catch the configuration error.' This encourages honesty and learning.
Scenario: Writing a Design Doc or RFC
Design docs and RFCs propose technical solutions and invite feedback. They require clear structure and professional phrases to present options, trade-offs, and recommendations.
| Term | Meaning |
|---|---|
| Stating the problem | This document addresses the problem of... |
| Proposing a solution | The proposed approach is to... |
| Presenting alternatives | We considered the following alternatives: |
| Explaining trade-offs | The trade-off is that X provides Y but at the cost of Z. |
| Acknowledging limitations | This proposal does not address... / Out of scope: |
| Requesting feedback | Feedback is requested on the following areas: |
| Citing prior work | As documented in [RFC-123], the current system... |
| Summarizing a decision | Based on the above analysis, the recommendation is to... |
Design Doc Sentences
- This document addresses the problem of slow API response times under high load.
- The proposed approach is to introduce a caching layer using Redis.
- We considered the following alternatives: in-memory caching, CDN-based caching, and database query optimization.
- The trade-off is that Redis adds operational complexity but significantly reduces latency.
- Out of scope: This proposal does not cover cache invalidation strategies for real-time data.
- Feedback is requested on the chosen TTL values and failover behavior.
Complete these design doc sentences with appropriate phrases.
Complete the sentence
Type the missing word or phrase.
______ the problem of database connection pool exhaustion during traffic spikes.
Complete the sentence
Type the missing word or phrase.
______ the following alternatives: horizontal scaling, connection pooling, and read replicas.
Complete the sentence
Type the missing word or phrase.
______ Redis provides lower latency but requires additional infrastructure.
Practice Exercises
Match each document type to its primary purpose.
Rewrite for work
Write what this document type or term is used for in one short sentence.
What is the primary purpose of a RFC in technical documentation?
Rewrite for work
Write what this document type or term is used for in one short sentence.
What is the primary purpose of a Spike in technical documentation?
Rewrite for work
Write what this document type or term is used for in one short sentence.
What is the primary purpose of a Postmortem in technical documentation?
Rewrite for work
Write what this document type or term is used for in one short sentence.
What is the primary purpose of a ADR in technical documentation?
Rewrite for work
Write what this document type or term is used for in one short sentence.
What is the primary purpose of a Runbook in technical documentation?
Choose the best option for each question.
Multiple choice
Choose the best answer.
Which term describes studying or working intensively on a topic in a short time?
Multiple choice
Choose the best answer.
What do we call the fundamental reason an incident occurred?
Multiple choice
Choose the best answer.
Which phrase is most appropriate for a formal design doc?