Technical Writing

Summary

Engineers write more than they present. This chapter covers the full spectrum of technical writing -- proposals, reports, documentation standards, requirements documents, API documentation, and code comments. You will learn to write effective emails using Smart Brevity, craft meeting notes and status updates, and develop style guides for consistency. The chapter also covers engineering case studies as a bridge between storytelling and technical writing.

Concepts Covered

This chapter covers the following 21 concepts from the learning graph:

Technical Writing
Technical Proposals
Technical Reports
Documentation Standards
Requirements Documents
User Documentation
API Documentation
Code Comments
Email Communication
Meeting Notes
Progress Reports
Status Updates
White Papers
Specification Writing
Style Guides
Tone in Writing
Grammar and Mechanics
Paragraph Structure
Transition Words
Document Templates
Engineering Case Studies

Prerequisites

This chapter builds on concepts from:

Why Technical Writing Matters for Engineers

If you spend most of your day writing code, you might assume that writing prose is someone else's job. In reality, the average software or electrical engineer spends between 20% and 40% of their working hours producing written artifacts -- emails, design documents, pull-request descriptions, status updates, incident reports, and requirements specifications. When you add code comments and commit messages, that percentage rises further. Technical writing is the discipline of producing clear, accurate, and usable documents that help teams build, maintain, and improve engineered systems.

The difference between a well-written design proposal and a poorly written one is not just aesthetic. It is the difference between a project that gets funded and one that does not, between a system that gets built correctly and one that requires costly rework. Unlike a presentation that reaches a roomful of people once, a written document can circulate to hundreds of stakeholders over months or years. Its clarity -- or its ambiguity -- compounds over time.

This chapter organizes technical writing into three layers. First, we cover the building blocks -- paragraph structure, transitions, tone, and grammar. Second, we cover the document types that engineers produce most often -- proposals, reports, specifications, documentation, and emails. Third, we cover the systems that keep writing consistent across teams -- style guides, templates, and documentation standards.

Welcome to Technical Writing

You already write every day -- emails, chat messages, code comments, commit messages. This chapter will help you write all of those more effectively, and then teach you the longer-form documents that define your engineering career.

Building Block 1: Paragraph Structure

A paragraph structure in technical writing differs from the paragraphs you wrote in literature courses. Technical paragraphs are shorter, more focused, and built around a single controlling idea. The standard structure has three parts:

Topic sentence -- States the paragraph's main claim or point. Place it first so that a reader who skims catches the key idea.
Supporting sentences -- Provide evidence, examples, data, or reasoning that develop the topic sentence.
Closing or transition sentence -- Connects the current paragraph to the next one, or summarizes the implication of the evidence.

A common mistake in engineering writing is the "data dump" paragraph -- a long block of facts with no topic sentence to tell the reader what the facts mean. Another common mistake is the paragraph that tries to cover two or three ideas at once. When you find yourself writing a paragraph longer than six or seven sentences, check whether it actually contains two separate ideas that deserve their own paragraphs.

Building Block 2: Transition Words

Transition words are the connective tissue between sentences and between paragraphs. They signal the logical relationship between ideas, helping the reader follow your argument without re-reading. The following table groups the most useful transitions by function:

Function	Transition Words	Example
Addition	also, furthermore, moreover, in addition	The system also reduces latency by 30%.
Contrast	however, nevertheless, on the other hand, whereas	However, this approach increases memory usage.
Cause/Effect	therefore, consequently, as a result, because	As a result, the pipeline fails under load.
Sequence	first, next, then, finally, subsequently	First, the client sends a handshake request.
Example	for instance, specifically, such as, to illustrate	For instance, the retry logic handles 503 errors.
Summary	in summary, overall, to conclude, in short	In summary, the migration requires three phases.

Without transitions, technical writing reads like a series of disconnected facts. With appropriate transitions, the same facts form a coherent argument. A useful self-editing technique is to read only the first sentence of each paragraph in sequence. If those sentences form a logical chain, your transitions are working. If the chain has gaps, add transitional language to bridge them.

Building Block 3: Tone in Writing

Tone in writing is the attitude or stance that the writer conveys toward the subject and the reader. In technical writing, tone should be professional, objective, and respectful. This does not mean robotic -- it means choosing a register that fits the context.

The following guidelines help you calibrate tone across different writing situations:

Formal documents (proposals, specifications, white papers): Use third person ("the system performs"), avoid contractions ("do not" rather than "don't"), and maintain a neutral, evidence-based stance.
Semi-formal documents (design docs, meeting notes, progress reports): Second person ("you") and contractions are acceptable. The tone is direct and collegial.
Informal communication (email, chat, code review comments): First person and conversational language are appropriate, but remain respectful and constructive. Avoid sarcasm -- it rarely survives the transition from speech to text.

One dimension of tone that engineers often overlook is directness vs. hedging. Compare "This approach will fail under load" with "This approach might have some challenges in certain scenarios." The first is direct and actionable. The second is so heavily hedged that it communicates nothing. In engineering writing, err on the side of directness. State your claims clearly and support them with evidence.

Building Block 4: Grammar and Mechanics

Grammar and mechanics may feel like details, but in technical writing they directly affect meaning. A misplaced modifier can change the interpretation of a requirement. A missing comma can create ambiguity in a specification. Engineers do not need to master every rule of English grammar, but they do need to master the rules that prevent misinterpretation.

The most consequential grammar issues in technical writing are:

Subject-verb agreement in complex sentences: "The set of test results shows [not show] a regression."
Dangling modifiers: "After running the tests, the bug was found" -- who ran the tests? Rewrite as "After running the tests, the team found the bug."
Pronoun ambiguity: "The server sends data to the client, and it crashes" -- what crashes? Name the subject explicitly.
Parallel structure in lists: Every item in a bulleted list should follow the same grammatical form. If the first item starts with a verb, all items should start with a verb.
Consistent tense: Use present tense for descriptions of how a system works ("the module parses the input"), past tense for completed work ("the team implemented the feature"), and future tense for planned work ("the next sprint will address performance").

When in doubt, read your sentence aloud. If you stumble, the reader will too. Technical writing does not need to be beautiful. It needs to be unambiguous.

The Spectrum of Technical Documents

Engineers produce many types of documents across a project's lifecycle. The table below maps the most common document types to their purpose, audience, and typical length:

Document Type	Purpose	Primary Audience	Typical Length
Technical Proposal	Persuade decision-makers to fund or approve work	Managers, sponsors, clients	5-20 pages
Technical Report	Present findings, analysis, or results	Engineers, stakeholders	5-50 pages
Requirements Document	Define what a system must do	Engineers, QA, product managers	10-100+ pages
Specification	Define how a system must behave in exact terms	Implementers, testers	5-50 pages
White Paper	Explore a problem and argue for a solution approach	Technical decision-makers	5-15 pages
User Documentation	Teach end users how to operate a system	End users of all skill levels	Varies widely
API Documentation	Teach developers how to integrate with a system	External or internal developers	Varies widely
Progress Report	Summarize work completed during a time period	Managers, stakeholders	1-3 pages
Status Update	Provide a snapshot of current project state	Team members, managers	0.5-1 page
Engineering Case Study	Analyze a real-world project for lessons learned	Students, fellow engineers	3-10 pages

Each document type has its own conventions and structures. The following sections cover the most important ones in detail.

Technical Proposals

A technical proposal is a persuasive document that argues for a course of action -- building a new system, adopting a technology, funding a research effort, or solving a specific problem. Proposals are how engineers turn ideas into funded projects.

Every effective technical proposal answers five questions:

What is the problem? Define the pain point clearly and quantify it if possible ("The current build system takes 47 minutes, blocking developer productivity").
Why does it matter? Connect the problem to business outcomes, user experience, or system reliability.
What is the proposed solution? Describe the approach at a level appropriate for the audience -- high-level for executives, detailed for engineering review boards.
What are the trade-offs? Acknowledge alternatives you considered and explain why your proposed solution is the best fit.
What resources are needed? Specify timeline, team size, infrastructure costs, and any dependencies.

Proposals fail most often because they skip question 1 and jump straight to the solution. Decision-makers need to understand why before they can evaluate what. Structure your proposal so that a reader who stops after the first page still understands the problem and the high-level solution.

Technical Reports

A technical report documents the results of an investigation, experiment, design process, or project. Unlike proposals, which look forward, reports look backward -- they describe what was done, what was found, and what it means.

The standard structure for a technical report follows this sequence:

Abstract or Executive Summary -- A self-contained summary of the entire report in one paragraph (for an abstract) or one page (for an executive summary)
Introduction -- Context, motivation, and scope of the work
Methodology -- How the work was conducted, in enough detail for replication
Results -- What was observed or produced, presented with data, tables, and figures
Discussion -- What the results mean, how they compare to expectations, and what limitations apply
Conclusions and Recommendations -- Summary of findings and suggested next steps
References -- Sources cited in the report

The most important skill in report writing is separating results from interpretation. The Results section presents data without judgment: "The system achieved 99.2% uptime over the 30-day test period." The Discussion section interprets: "This exceeds the 99.0% target specified in the SLA, suggesting the redundancy architecture is sufficient for production deployment."

Requirements Documents and Specification Writing

Requirements documents define what a system must do. Specification writing defines how a system must behave, in precise, testable terms. Together, they form the contractual foundation of any engineering project.

Good requirements share four properties:

Unambiguous -- Each requirement has exactly one interpretation
Testable -- You can write a test that proves the requirement is met or not met
Traceable -- Each requirement has a unique identifier that links it to tests, designs, and code
Prioritized -- Requirements are ranked by importance (must-have, should-have, nice-to-have)

Consider the difference between a weak requirement and a strong one:

Weak: "The system should be fast." (Fast compared to what? Under what conditions?)
Strong: "The system shall return search results within 200 milliseconds for queries of up to 10,000 records, measured at the 95th percentile under a load of 500 concurrent users."

The strong version is unambiguous, testable, and specific. Specification writing takes this precision further by defining interfaces, data formats, error codes, and boundary conditions. Specifications serve as the agreement between the team that builds a system and the team that tests it. Every ambiguity in a specification becomes a potential defect.

User Documentation

User documentation teaches people how to use a product or system. Unlike requirements and specifications, which target engineers, user documentation targets the people who will actually operate, configure, or troubleshoot the system in production.

Effective user documentation has three characteristics:

Task-oriented -- Organized around what users want to do, not around how the system is built. Users do not want to understand your architecture; they want to complete a task.
Layered -- Provides quick-start guides for beginners, detailed references for experts, and troubleshooting sections for everyone.
Accurate -- Updated whenever the product changes. Outdated documentation is worse than no documentation because it erodes trust.

A practical framework for writing user documentation is the "goal-steps-result" pattern: state the user's goal, list the steps to achieve it, and describe the expected result so the user knows they succeeded.

API Documentation

API documentation is user documentation for developers. It teaches external or internal developers how to integrate with your system's programmatic interfaces. Well-documented APIs see higher adoption rates, fewer support requests, and fewer integration bugs.

The essential sections of API documentation are:

Authentication -- How to obtain and use credentials
Endpoints / Methods -- What operations are available, including URL patterns, HTTP methods, request parameters, and response formats
Examples -- Working code samples in the languages your audience uses most
Error codes -- What can go wrong and how to handle it
Rate limits and quotas -- Operational constraints the developer must respect

The gold standard in API documentation is that a developer can make a successful API call within 15 minutes of reading the docs. If your documentation cannot pass that test, it needs revision. Include copy-pasteable code examples for the most common use cases.

Pro Tip

The best API documentation is written before the API is built. Writing docs first forces you to think from the consumer's perspective, which almost always produces a better-designed API. This practice is called "documentation-driven development."

Code Comments

Code comments are the most frequent form of technical writing an engineer produces. They explain why code exists, not what it does -- the code itself already shows what it does. Good comments explain intent, constraints, trade-offs, and non-obvious decisions.

The following guidelines distinguish helpful comments from noise:

Comment the "why," not the "what": // Retry up to 3 times because the upstream service has transient failures during deployments is useful. // increment counter by 1 is noise.
Document interfaces, not implementations: Function signatures, class headers, and module-level docstrings should explain contracts, parameters, return values, and side effects.
Flag non-obvious decisions: If you chose an O(n^2) algorithm over an O(n log n) one because the input size is always under 20, say so. The next engineer who reads your code will otherwise "fix" your deliberate choice.
Keep comments current: A comment that contradicts the code is worse than no comment at all. When you change code, update the adjacent comments.

Email Communication

Email communication remains the primary channel for asynchronous professional communication. Engineers send and receive dozens of emails daily, and poorly written emails waste hours of collective time across a team.

Apply the Smart Brevity framework from Chapter 4 to every professional email:

Subject line as headline -- State the purpose and any required action: "Decision Needed: Database migration timeline" is better than "Quick question."
First sentence delivers the point -- Do not bury the request in paragraph three. Start with what you need: "I need your approval by Friday to proceed with the PostgreSQL migration."
Body provides context -- Use bullet points for supporting details. Keep paragraphs to three sentences or fewer.
Close with a clear call to action -- Specify who needs to do what by when.

An example of an effective engineering email:

Subject: Action Required: Review proposed API rate limits by Thursday

Hi Team,

I need your feedback on the proposed API rate limits by end of day Thursday so we can finalize the v2.0 specification.

The proposed limits:

Free tier: 100 requests/minute

Pro tier: 1,000 requests/minute

Enterprise tier: custom, negotiated per contract

These are based on our current traffic analysis, which shows 95% of free-tier users make fewer than 60 requests/minute. The full analysis is in the attached spreadsheet.

Please reply with "approved" or your specific concerns.

Thanks, Alex

This email is scannable, actionable, and respectful of the reader's time.

Meeting Notes

Meeting notes serve two purposes: they create a record of what was decided, and they hold people accountable for what they committed to do. Without notes, meetings are ephemeral -- decisions get forgotten, action items drift, and the same discussions recur weeks later.

Effective meeting notes follow a consistent structure:

Date, attendees, and agenda -- Who was there and what was discussed
Key decisions -- What was decided, stated clearly and unambiguously
Action items -- Who committed to doing what, with a specific deadline
Open questions -- Unresolved issues that need follow-up

Meeting notes should be distributed within 24 hours while the discussion is still fresh. Keep them concise -- a one-page summary of a one-hour meeting is appropriate. The test of good meeting notes is whether a colleague who missed the meeting can read the notes and understand what happened.

Progress Reports and Status Updates

Progress reports and status updates are periodic documents that communicate project state to stakeholders. They differ in scope and frequency:

A progress report is a detailed account of work completed during a reporting period (typically weekly, biweekly, or monthly). It includes accomplishments, challenges encountered, metrics, and plans for the next period.
A status update is a brief, high-frequency snapshot (often daily or every few days) that answers three questions: What did I accomplish? What am I working on next? What is blocking me?

Both document types benefit from the following practices:

Lead with accomplishments, not activities. "Reduced API response time from 450ms to 120ms" is stronger than "Worked on API performance."
Quantify wherever possible. Numbers give stakeholders a concrete sense of progress.
Flag risks early. A status update that says "everything is fine" for six weeks and then reports a three-week delay has failed its purpose. Report risks when you first see them, not when they become crises.

White Papers

A white paper is a long-form persuasive document that explores a technical problem and argues for a particular solution approach. White papers are common in industry, where they serve as thought leadership, pre-sales materials, or internal decision-support documents. They sit between a technical report (which presents findings) and a technical proposal (which requests approval).

The structure of a white paper typically follows this arc:

Define the problem and establish its significance
Survey existing approaches and their limitations
Present the proposed approach with technical detail
Provide evidence -- benchmarks, case studies, theoretical analysis
Discuss implications, limitations, and future directions

White papers differ from academic papers in tone and audience. They are written for practitioners, not reviewers. They favor clarity and practical relevance over methodological rigor. A strong white paper makes the reader say, "I understand this problem better now, and this solution makes sense."

Documentation Standards and Style Guides

Documentation standards are organizational rules that govern how documents are created, structured, reviewed, and maintained. They ensure that documents across a team or company are consistent, findable, and trustworthy.

Style guides are a specific type of documentation standard that defines writing conventions -- terminology, formatting, voice, and usage rules. A style guide answers questions like:

Do we write "login," "log in," or "log-in"?
Do we use Oxford commas?
Do we write procedures in second person imperative ("Click the button") or third person ("The user clicks the button")?
How do we capitalize product names and feature names?

Without a style guide, a team of ten engineers will produce ten slightly different writing styles, creating an inconsistent experience for readers. Major technology companies publish their style guides publicly -- Google, Microsoft, and Apple all maintain developer documentation style guides that are worth studying.

The following list identifies the core components of a technical style guide:

Terminology glossary -- Approved terms and their definitions, plus terms to avoid
Formatting rules -- Heading levels, code formatting, list punctuation, image captioning
Voice and tone -- Active vs. passive voice guidance, formality level, person (first, second, third)
Templates -- Standard structures for each document type
Review and approval workflow -- Who reviews, what is checked, how changes are tracked

Document Templates

Document templates are pre-built document structures that enforce consistency and reduce the cognitive load of starting a new document. Instead of staring at a blank page and deciding how to organize a design review, you open a template that already contains the sections you need.

Effective templates share three qualities:

Just enough structure -- They provide section headings and brief instructions for what belongs in each section, without being so rigid that they prevent adaptation.
Aligned with the style guide -- Templates embody the formatting, terminology, and tone standards defined in the style guide.
Easy to find -- Templates stored in a shared, well-organized repository get used. Templates buried in someone's email archive do not.

Common engineering templates include design document templates, incident postmortem templates, RFC (Request for Comments) templates, and meeting agenda templates. If your team does not have templates for these document types, creating them is one of the highest-leverage contributions you can make.

Engineering Case Studies

Engineering case studies analyze real-world projects to extract lessons learned. They are the bridge between storytelling (Chapter 9) and technical writing -- they use narrative structure to make technical content memorable and actionable.

A well-structured engineering case study includes:

Context -- The organization, the project, and the constraints
Challenge -- The specific problem or decision point
Approach -- What the team did and why
Results -- Measurable outcomes, including both successes and failures
Lessons learned -- Generalizable insights that readers can apply to their own work

Case studies are valuable because they capture situated knowledge -- the messy, context-dependent reasoning that textbooks and documentation rarely include. When you read that a team chose eventual consistency over strong consistency for their distributed database, and you learn the specific load patterns, latency requirements, and organizational constraints that drove that decision, you gain practical wisdom that no API reference can provide.

Think About It

Every project you work on is a potential case study. Start keeping brief notes about the decisions your team makes and why. These notes will become invaluable references for future projects -- and for your own career portfolio.

Putting the Pieces Together

Technical writing is not a single skill. It is a system of interlocking practices -- paragraph construction, transitional logic, tonal calibration, grammatical precision, document structure, and organizational standards -- that work together to produce documents people actually read and act on.

The most effective approach is to build from the inside out. Master paragraph structure and transitions first, because every document type depends on them. Then learn the conventions of the specific document types you produce most often -- for most early-career engineers, that means emails, code comments, status updates, and design documents. Finally, contribute to your team's style guides and templates so that the entire team benefits from clearer writing.

Writing is thinking made visible. When your writing is clear, it is because your thinking is clear. When your writing is muddled, it is often a signal that you have not yet fully worked through the problem. This is why the best engineers treat writing not as a chore that follows the real work, but as an integral part of the engineering process itself.

Key Takeaways

Technical writing is the most frequent form of communication for engineers, consuming 20-40% of working time
Strong paragraphs start with a topic sentence, develop one idea with evidence, and connect to the next paragraph with transitions
Tone should match the formality of the document type -- formal for proposals and specifications, conversational for email and code reviews
Grammar errors in technical writing are not cosmetic -- they create ambiguity that causes defects and miscommunication
Technical proposals answer five questions: What is the problem? Why does it matter? What is the solution? What are the trade-offs? What resources are needed?
Requirements must be unambiguous, testable, traceable, and prioritized
API documentation succeeds when a developer can make a successful call within 15 minutes
Code comments explain why, not what -- the code already shows what it does
Emails should lead with the point, use bullet points for context, and close with a specific call to action
Style guides and templates are force multipliers -- they make every writer on the team more consistent and more efficient

Chapter 11 Quiz

Next Chapter: AI and Communication -- Learn how AI tools are transforming technical communication and how to use them effectively while maintaining your authentic voice.