10 Rules I Learned About Technical Writing
What I Learned from Writing a Book
Hello! Today, let’s talk about technical writing. By the way, we are approaching the 1,000 subscribers. Be prepared for a special post when we will reach that milestone. 👀
As you may know, in 2022, I published my first (and last) book, 100 Go Mistakes and How to Avoid Them. While I had already been maintaining a technical blog for more than a decade, I learned a ton during this experience. Here are ten rules I learned about technical writing while writing my book.
Manage reader expectations: Readers don't just read; they interpret. As a writer, you need to manage their expectations carefully and make sure the interpretive decisions they make are always clear and unambiguous.
Avoid naked assertions: Never make a statement without backing it up. For example: "X should be avoided"—but why? What makes X problematic? Why is that relevant for the reader? If you don't make it explicit, the reader can make false assumptions or fail to understand the importance of a topic.
Make consequences clear: When explaining a problem, always state the consequences clearly. For example: "Unfortunately, X implies Y" => What's precisely the problem with Y?
Don’t assume simplicity: Avoid sentences such as "it's simple" or "the solution is easy". Imagine reading a solution you’re struggling to understand, only to be told it’s “simple“. Just because something is simple for you doesn’t mean it’s simple for your reader. Empathy matters.
Clarify vague pronouns: For example, "it" is quite often vague. If "it" refers to something mentioned earlier, make sure it's explicit for the reader. If not, replace "it" with the actual subject or rephrase the sentence.
Reinforce key concepts: Reinforcement is a great way to increase the efficiency of teaching. For example, if you consider that a topic is difficult for the reader to understand, try explaining it in a different way or from another angle.
Reiterate core principles: Sometimes, it can be beneficial to repeat key points differently to increase comprehension. It's called reinforcement, and it can be a way to make sure an issue or a problem is clear to the reader.
Ask engaging questions: Questions can be an excellent way to grab the reader's attention. For example: "What's the issue with this code?" or "How can we validate our assumption?". Asking questions encourages readers to think critically and engage with the material.
Clarify code blocks: Never leave code blocks up for interpretation:
Before the code: Explain what the code is intended to do.
After the code: Describe what the code did and make explicit what's important about the code.
Favor just-in-time (JIT) over just-in-case (JIC) teaching: JIT is a teaching strategy to favor active learning. Sentences are built in a logical way to improve how effective an asset will be for the reader. JIC may confuse the reader about the exact train of thought with unnecessary information.
For conclusions, focus on skills, not just knowledge: In your conclusions, emphasize the skills learned, not the knowledge gained. For example, don't write "using X allows doing Y" but "to do Y, we have to use X".
Thanks to Manning, and especially Doug Rudder, from whom I learned a ton.
Explore Further
- and // I just finished reading this book last weekend, and I highly recommend it
Write that blog! // A great newsletter from the same folks, which I also recommend.
Google Technical Writing Courses // A lot of actionable advice.
What do you think about these rules? Are there any other rules you’re living by when writing technical content?
Last updated: March 9, 2025