Technical Writing#

The ability to explain complex technical ideas clearly — in docs, READMEs, commit messages, design proposals, and decision records — is what separates a productive engineer from a 10x force multiplier. Writing is thinking made visible. If you can’t write it down clearly, you probably don’t understand it clearly yet.

Why Technical Writing Matters#

Audience Awareness#

The single most important skill in technical writing. Before writing anything, ask:

Audience Spectrum#

Writing READMEs#

A README is the front door of your project. If it doesn’t answer “what is this, how do I run it, and where do I go next?” within 60 seconds, it has failed.

README Structure#

# Project Name

One-sentence description of what this does and why.

## Quick Start

The fastest path from clone to running code.

## Prerequisites

What you need installed before anything works.

## Installation / Setup

Step-by-step. Copy-paste-able commands.

## Usage

How to use the thing once it's running. Common commands.

## Configuration

Environment variables, config files, feature flags.

## Architecture (optional)

Brief overview for orientation. Link to deeper docs.

## Contributing

How to submit changes. Branch naming, PR process.

## Troubleshooting (optional)

Common problems and their solutions.

README Principles#

Writing Commit Messages#

Every commit message is a letter to future developers (including yourself). It costs seconds to write well, and saves hours during debugging, code archaeology, and git bisect.

Anatomy of a Good Commit Message#

<type>(<scope>): <short summary in imperative mood>

<body: explain WHY, not WHAT — the diff shows what>

<footer: ticket reference, breaking changes, co-authors>

Commit Message Rules#

When the Body Matters#

Not every commit needs a body. Use one when:

• The why isn’t obvious from the diff
• You chose between alternatives (briefly state why)
• The change has non-obvious consequences
• You’re working around a known issue (link it)

Architecture Decision Records (ADRs)#

An ADR captures a significant technical decision with its context and consequences. ADRs prevent the “why did we do it this way?” question from recurring indefinitely.

When to Write an ADR#

Write an ADR when:

• Choosing between competing technologies or approaches
• Making a decision that would be expensive to reverse
• Deviating from an established pattern
• The reasoning might not be obvious in 6 months

ADR Structure#

ADR Writing Tips#

• Write the Context section for someone who joins the team next year
• Include the alternatives you considered and why you rejected them
• Be honest about trade-offs — every decision has downsides
• Keep them short — if it’s over 2 pages, you’re writing a design doc
• Number them sequentially. Don’t delete or reorder. Supersede instead.

Requests for Comments (RFCs)#

An RFC is a proposal for a significant change that invites structured feedback before implementation begins. Unlike ADRs (which record decisions already made), RFCs are pre-decision documents.

When to Write an RFC#

RFC Structure#

# RFC: [Title]

**Author:** [name]
**Status:** Draft | In Review | Accepted | Rejected | Withdrawn
**Date:** [date]
**Reviewers:** [names]

## Summary

[1-2 sentences: what you're proposing]

## Motivation

[Why this change is needed. What problem it solves.]

## Proposed Design

[The solution in detail. Diagrams welcome.]

## Alternatives Considered

[What else you evaluated and why you didn't choose it.]

## Risks and Mitigations

[What could go wrong and how you'd handle it.]

## Open Questions

[Things you're unsure about and want input on.]

## Timeline

[Rough estimate of implementation effort.]

RFC Process Tips#

• Share early (it’s a Draft, not a finished product)
• Actively solicit feedback — don’t just post and hope
• Set a review deadline (1-2 weeks is typical)
• Respond to every comment, even if the answer is “won’t do”
• Update the document as decisions are made during review

General Technical Writing Principles#

Clarity Checklist#

The Inverted Pyramid#

Borrowed from journalism — put the most important information first:

1. The conclusion / answer / decision         ← Most readers stop here
2. The supporting evidence / reasoning        ← Interested readers continue
3. The full context and background            ← Deep-dive readers reach here

This respects your reader’s time. Engineers scanning docs in a hurry get value from the first paragraph alone.

Technical vs Conversational Tone#

Common Anti-Patterns#

Key Takeaways#

• Know your audience before you write a single word — it determines everything else
• READMEs should get someone from zero to running in under 5 minutes
• Commit messages are for future debuggers — explain why, the diff shows what
• ADRs prevent “why did we do this?” from being asked repeatedly. Write them for decisions that cost money to reverse
• RFCs invite feedback before code exists — much cheaper than rework after implementation
• Use the inverted pyramid: conclusion first, details second, background last
• Technical writing is a practice. The more you write, the clearer your thinking becomes