I was recently chatting with a colleague about how to write technical documents, and they asked if I had any tips. I wouldn't call myself an expert, but I do enjoy writing technical documents (like design docs). I shared what I think works, and my colleague found it helpful — so I figured I'd write it up in my favorite medium: words! 😊

The kinds of documents I'm talking about here are Technical Design Documents (TDDs), RFCs (Requests for Comments), and similar artifacts — documents that communicate a technical idea for feedback and review. The goal is to write them so that even someone unfamiliar with the domain can follow along.

Through that conversation, I realized I have three main tips:

1. Start with the headline (summary)
2. Flow from abstract to specific
3. Explain the same thing three times

Let me walk through each one in more detail.

1. Start with the Headline (Summary)

The first thing to keep in mind is that not everyone will read the document from start to finish. Some people might read only the first few paragraphs and move on. That's why it's so important to put the most critical information up front.

You don't have to literally call the section "Headline," but if your Executive Summary or Introduction covers the key points right away, you can deliver 80% of the meaning to 80% of your readers¹.

For example:

Summary

This proposal addresses the problem of processing foo events at scale and recommends introducing an event-sourcing architecture to decouple event production from consumption. Kafka is recommended as the best-fit technology for this architecture, though other options are discussed.

Key takeaway:

• Lead with what matters most!
• Deliver 80% of the meaning in the summary/introduction

2. Flow from Abstract to Specific

Whenever I write a document, I try to always move from abstract to specific. In practice, that means the document first explains the problem and its context, and only then discusses the solution.

When presenting the solution, I start with a high-level overview before diving into the details of each component.

This lets readers build up context progressively as they read. They first understand the problem, then see the big picture of the solution, and finally work through the specifics.

Here's an example:

Proposal

The high-level architecture for processing foo events is as follows:

1. The foo processor publishes events to Kafka.
2. One consumer reads these events and stores them in S3.
3. Another consumer reads these events and stores them in Postgres.

Each step is described in more detail below.

1. Publishing foo events to Kafka

…

2. Storing events in S3

…

3. Storing events in Postgres

…

Key takeaway:

• Problem and context → solution overview → detailed explanation
• Structure the document so readers can go progressively deeper

3. Explain the Same Thing Three Times

Finally, when communicating a technical concept, I try to explain it in three different ways.

I think this is the hardest part of writing technical documents. It's not easy to take an idea you understand clearly and convey it accurately to someone who doesn't know it yet. And really, that's the whole point of writing the document in the first place!

To avoid misunderstanding, there are two pitfalls to watch for:

• The reader thinks they understood, but actually got it wrong
• The way you explained it makes it hard for the reader to understand at all

By explaining the same thing three times, I try to:

• Reduce ambiguity
• Reach the same idea from multiple angles

Here are some formats you can use:

• Prose (narrative description)
• List (bullets or numbered steps)
• Component diagram (architecture diagram)
• Sequence diagram

Let me reuse the earlier example to show this in action.

In prose:

The foo producer publishes foo events to a Kafka topic called foo.created. Two consumers read from this topic: the S3 consumer and the Postgres consumer. The S3 consumer receives foo.created events and stores them as objects in S3, while the Postgres consumer inserts new records into the Postgres database.

As a list:

When a new foo is created, we handle it as follows:

• A Kafka producer sends a new foo.created event to Kafka.
• The foo.created event is consumed and stored in S3.
• The foo.created event is consumed and a new record is inserted into Postgres.

Component diagram (architecture diagram):

Sequence diagram:

In the end:

"I try to communicate ideas in as many formats as possible — prose, diagrams, and more — to make them as accessible as I can."

Key takeaway:

• Repeat the same content in multiple formats (prose, lists, diagrams)
• Reduce misunderstanding and improve comprehension for a wider audience

Wrapping Up

I hope these tips are helpful the next time you sit down to write a technical document! For me, writing documents is a continuous journey of learning, refining, and reflecting. I may well come back to this post in a few years and find new tips to add.

Happy writing! 📚

¹ All statistics in this post are completely made up! 😄

Key Takeaways

• Headline / Summary
• Abstract → Specific
• Explain three times
• Avoid misunderstanding
• Multiple formats (prose, lists, diagrams)
• Document structure
• Feedback and review