5 Mistakes That Made My Documents Terrible

Writing tips that helped me go from writing terrible documents to good ones.

Are you are an aspiring tech lead and felt the following:

1. I cannot write good technical documents

2. How is my lead churning such amazing documents?

3. I have already spent hours on this document and it is still terrible, I don’t feel productive.

As a leader, you need to communicate vision, project proposals, design, etc. You may do a good job explaining things face-to-face, but do you find yourself answering too many trivial questions in your document, or are you getting feedback that the document isn't clear?

You are not alone! I faced the same challenge, and it wasn't until someone showed me the right way that I felt this skill was achievable.

---

The focus of this article is writing vision, project proposals, design documents or documents to resolve disagreements. This article does not cover writing good runbooks or product documentation. You can checkout my old article How to Write Good Runbooks

---

Avoiding these five mistakes was a crucial step for me.

1. Treating it as a chore 🚫💼

I assumed my job was primarily to write code and that everything else was a distraction. I would scribble down a basic document and share it. Later, I would be annoyed when leadership had seemingly trivial questions. I even limited the time I spent on writing them. Thereby, I never invested in learning the skill.

2. Not writing it for one audience 🎯👥

I tended to write documents for an imaginary set of people who didn’t share the same context on the problem. In one section, I wrote paragraphs providing context that my actual audience didn't need. In the other section, I wrote it for someone with too much context.

Also I would proof-read the document superficially and only fix the obvious typos. I didn’t focus on how they could misinterpret the message.

Note, writing a document for your team vs your manager vs a different team will need different kind of context and justification.

3. Not having a clear top-down message 📉🔍

I buried the core message of the document within context, justification and urgency. This was worse for vision documents or project proposals for ambiguous problems.

E.g., if I wanted to share "how to scale API X for 5 years," I would list many options with trade-offs and lots of detail. However, I might fail to highlight which option I chose, whether I needed help making the decision, or if I proposed a hybrid approach.

4. Trying to be concise ✂️📄

When I got the feedback that my documents were verbose, I tried to keep them short. However, I would try to be concise even before I had my first draft. I started skipping important details that were necessary for the context. I eliminated sentences that were important for a smooth flow of thoughts. That made the content complex.

This impacted readability and confused my readers. In fact, when key details were skipped, my readers made their own assumptions and took away the wrong message.

5. Not using visuals for complex topics 🖼️📊

This sounds pretty basic and hard to miss. But still, I would be caught up in the moment and write verbose explanations. Adding a flow chart, comparison table, timeline view or other diagrams could have improved readability.

As an example, the following visual shows how bad documents can confuse the readers

Turning point for me 🔁💡

I worked with a Sr. Staff Engineer and saw their writing process while writing a vision document. I was amazed at their attention to detail and patience. They weren’t in a rush to share the document with everyone. They even sought early feedback from folks that were detached from the process.

This experience helped me see the aforementioned gaps. I saw the value that document brought to all stakeholders. Thereafter, I started valuing this work more than “coding”.

My Writing Steps 📝👣

1. Write the core message in a single sentence.

   1. I am writing to tell you “we should deprecate API X in favor of Y because …” or “We should do XYZ about problem A because …”.

2. Determine the audience. In fact, I picture a person that I am writing the doc for.

3. Determine the context my audience needs.

   1. The hardest part is bringing the readers to the same level as me without boring them with unnecessary details or providing none.

4. Create an outline. This is the logical order of sections that explain and support the core message.

5. Then, I fill in the details as if I were explaining it verbally.

6. Next, I make editorial fixes and remove redundancies.

7. Add visuals wherever appropriate to simplify the explanation.

8. I even add meta descriptions for the sections to orient the reader.

   1. E.g., "I assume the reader knows about ABC," or "this section is still a work in progress," or "I am not sure if this is the right decision, but here are the trade-offs," or "this seems too ambitious, but here is how I think it is viable."

9. For the important documents, I will read them out loud, slowly.

   1. This helps me catch if my content is missing details or if the sentences are not connecting well with each other.

10. Finally, I may request a couple of early readers, who haven't heard me talk about this topic, to review it for readability.

Parting Note 💌📌

In school, I wrote terrible essays that lacked a cohesive structure. I didn’t learn the "right" way to write down my thoughts. This continued at work too, until the turning point I mentioned above. To be honest, I still make those mistakes. However, with practice, I have gotten better at correcting and avoiding them.

I may not be the best person to give you advice on how to write great documents. However, as someone who went from writing terrible documents to good ones, I can assure you that with enough practice and guidance, you can improve too.

---

🎤 Shoutout

1. Stick to boring architecture for as long as possible by

   Addy Osmani

2. I wish I started doing this on day 0 of my career as an engineer by

   Jordan Cutler

3. How to Create a Good Release Process by

   Luca Rossi

---

If you enjoyed this article then hit the ❤️ button. It really helps!

If you think someone else will benefit from this, then make sure to 🔁 share this post.