Writing Better Technical Documents

Five techniques that have helped me write better technical documents.

When I joined Code.org, several folks asked me what habits from Amazon I wanted to bring across with me. While Amazon has many peculiar qualities, the one I valued most was the culture of writing. As you’ve likely heard, Amazon values writing and using documents for decision making over creating slide decks.

A good document makes meetings more efficient. Spending the first 10-15 minutes reading a well-written document gets everyone on the same page (both literally and figuratively) much quicker than any slide deck can. A good document also increases critical thinking skills. While it’s possible to “wing” a presentation by assembling a few bullet points the night before, the same isn’t true with a good document. You must instead invest the time exploring many angles of a topic before you can confidently put it into words.

Writing, however, is hard. Coming from an engineering background, writing wasn’t (and still isn’t) as natural to me as other subjects. Over the past few years, I’ve found five techniques that help make for stronger technical documents. Here they are:

Tell a story

Storytelling isn’t just for works of fiction. A well-written technical document can still tell a story. The proposal for your next big idea can still have a protagonist, conflict, and a story-based narrative.

When applying this to technical documents, I start by putting myself in the reader’s position. Who is the protagonist that I want to present to the reader? What is the issue or conflict? How will the protagonist resolve this? Many of the promotion documents I wrote at Amazon followed this idea. The protagonist was, of course, the individual being put up for promotion, and I shared the conflicts and issues they faced along the way (which later on became the justification for moving to the next level). While it wasn’t a novel, these story constructs helped create a compelling case.

Two books that have helped me learn more about storytelling are Story by Robert McKee and On Writing by Stephen King. While it’s in depth and aimed at screenwriters, McKee’s book provides the foundation for good storytelling. King’s memoir is a unique and engaging perspective on becoming a writer. While it’s geared more towards fiction writers, I found much of the content still applies to writing non-fiction work.

Maintain a consistent style

Inconsistencies are easy to spot as a reader and notoriously difficult to see when you are writing. Yet, inconsistencies such as using 3rd Jan in one paragraph and 1/3 in the next will negatively affect how your document is received, even if the content is sound.

During my time at Amazon, I created a style guide that I referred to when writing or reviewing documents. A style guide is just a set of rules to ensure consistency throughout a document. For example, my rule for dates is to use 3 Jan vs. 1/3 for days and Jan 2022 vs. 1/2022 for months. I have many other rules that include the use of numbers, spacing, acronyms, and so on.

Building your own style guide is easy. I’d recommend starting with Elements of Style by William Strunk Jr. to learn about common patterns used in the publishing industry. As you get deeper into the subject, the Chicago Manual of Style by The University of Chicago Press Editorial Staff an invaluable resource for those documents that have to be perfect.

Strive for clarity

When writing about a technical subject, it’s easy to use a style that biases towards overly complex jargon. The illusion is that doing so will make you sound much smarter, but quite the opposite is true. Instead of writing a document that your professor would be proud of, try writing in a style that a 10th grader could read. (Look for a tool that supports the Flesch Reading Ease score to determine how readable your own work is).

One habit that helps is writing in the active voice. It wasn’t until I took a writing class at Amazon that I discovered I was writing mostly in the passive voice (i.e., The code is optimized to be secure) vs. an active voice (i.e., I’ve optimized the code to be secure). I now use several tools (e.g., ProWritingAid) that prevent too many passive voice sentences creeping back in.

Other books I would recommend include Sense of Style by Steven Pinker. Pinker covers an almost scientific approach for writing clearly and avoiding leaning too heavily towards an academic style. I also enjoyed On Writing Well by William Zinsser. One recommendation in Zinsser’s book is after you’ve completed your first draft, try to reduce the length of your prose by 50%. And once you’ve done that, try to reduce it again by another 50%. When I’ve used this approach with my own documents, it’s been a useful tool to distill down to the essence of what I’m wanting to say.

Use feedback loops

Writing is a journey of continual improvement and constructive feedback will help your documents become stronger.

There are many automated ways of generating feedback for your documents. I’ve had success with ProWritingAid as it integrates well with Google Docs, but most editors now support basic style and grammar checking.

Once you have addressed feedback using tools, ask other folks on your team to review your work, especially ahead of an important review. When they provide feedback, I recommend focusing on the areas they flag as confusing and think about how you can clarify these. Maybe it requires a stronger introduction or purpose? Maybe it’s the length of the paragraphs? Maybe you are using acronyms that the reader is less familiar with?

In addition, be a supportive reviewer for other writers on your team. At Amazon, when folks would send me documents to review, I would split my feedback into two parts: I’d cover the proposal (i.e., Let’s first discuss whether the idea makes sense) and then the writing style (i.e., I have some feedback on the grammar and structure of the document, if it is useful). On every occasion I shared feedback on the document’s style, it was well received.

Practice every day

Every time you put hands to keyboard is an opportunity to become a better writer. Putting together a quick email? Maybe that’s a chance to check for passive voice. Composing a LinkedIn post? How could that be more concise? It may take longer to create and review that outgoing note, but doing so can help form natural habits that will make your writing stronger.

Finally, besides practice, I’ve found that reading has made me a better writer. I always have a queue of books lined up, and even if they are on technical topics, it’s always fascinating to see how the author introduces the subject and keeps me, the reader, engaged.