Ways of Working
Technical Writing
Foundational
Engineers write constantly: PR descriptions, docs, design proposals, incident notes, messages. Clear writing saves everyone time; unclear writing wastes it. Writing well is not a talent you either have or do not. It is a skill you can learn: know your reader, lead with the point, and choose clear over clever.
Much of an engineer's impact travels through writing. For a distributed, async-leaning, growing team, writing is how decisions, context, and knowledge spread and last. The basics are simple and learnable: write for your specific reader, put the most important thing first, and use plain, concrete language. This is the skill behind Communication and Documentation as Code.
Write to be understood
- DoLead with the point: the conclusion, the request, or the key risk first (BLUF: bottom line up front). Then add the supporting detail for those who need it (see Communication).
- DoWrite for your specific reader and what they need to do or know. Match the depth and words to engineers, leadership, or non-technical readers.
- DoBe clear and concrete: short sentences, plain words, specific examples. Cut filler and trim down rather than padding out.
- DoStructure for scanning: headings, short paragraphs, lists, and meaningful titles. People skim.
- DoState assumptions and uncertainty clearly, and define terms and acronyms the reader may not know.
Common engineering writing
- DoPR descriptions: what changed, why, how it was tested, and what to look at, so reviewers can review well (see Code Review).
- DoDesign docs and proposals: the problem, the options considered, the decision, and the reason for it (lightweight ADRs), so the reasoning lasts (see Documentation as Code).
- DoIncident and postmortem write-ups: timeline, impact, cause, and fixes. Keep them factual and blameless (see Incident Readiness).
- DoCapture the why and the surprising parts in docs and comments. Let clear code show the what (see Coding Standards & Style).
- NeverPut secrets, credentials, or real customer or PII data into docs, messages, tickets, or examples (see Observability & Logging Hygiene).
Self-review checklist
- AskIs my main point in the first line, or buried?
- AskHave I written for this specific reader and what they need?
- AskCan it be shorter and clearer, and is it easy to scan?
- AskAre there any secrets or real PII in what I am writing?
Why it matters: Clear writing increases an engineer's impact. A good design doc aligns a team, a clear PR description speeds up review, and a precise incident note prevents the same problem happening again. Unclear writing wastes the time of everyone who reads it. Writing is one of the highest-value skills to develop, and it is fully learnable.