Struggling with writing technical documents?

What is your preferred language?

When I have to choose a language, I wish I always get the option of selecting Javascript as my primary language. ??

With my career laddering up, I am spending more time writing documents than coding in Javascript. My role demands writing design docs, strategy docs, DACIs, guided tutorials and many more docs which can't be written in any coding language.

Have you heard of this quote:

“Writes like an engineer”

It might sound like a compliment, but it isn't one. When it comes to writing, engineers are prone to procrastination because?the process of writing is hard – technically and emotionally.

Let me share my experience of learning how to create meaningful, impactful and precise documents. Although there are different rules for different types of documents, this blog will focus on general guidelines for writing any type of document.

The 7 Steps of writing a document

Step 1. The first step is to layout your document into sections with headings and sub-headings. For example, if you are writing a technical strategy doc. You can create sections like Background, Strategic Objectives, Guiding Principles, Execution Strategy, Caveats & Assumptions & Risks. Do this step recursively and keep breaking your sections into smaller sub-sections. But don't go beyond 1 or 2 levels deep.

Break it down into sections, headings only.

Step 2. In this step, under each section or sub-section start writing bullet points which describe your heading in the best possible way. It neither has to be proper sentences nor it is required to be in a meaningful sequence. Just jot down each and every idea or thought which can help you later to elaborate on the idea you want to convey through that particular section.

Fill in each section with relevant ideas.

Step 3. After writing down all the points, arrange them coherently to make sense when read together. While organising them in order, you might notice missing elements or a disconnect between two points. For example, consider it like a small story where every sentence is in a connected sequence with your previous and the next one.

Arrange the points under each section in clear and logical order.

Step 4. By now, your document has already begun to make sense. So let's refine it now. In this step, you should convert your points into proper sentences. Use a series of sentences grouped into paragraphs of decent size to build your section. Keep your sentences short and straightforward. Even at this point, don't worry about fancy words or phrases.

Convert the bullet points into meaningful sentences.

While constructing your sentences, you should remember that sentences must be:

• correct, giving out the right information. It's better not to say it than to say it incorrectly.
• concrete. Your statements must be action-driven and should show confidence.
• clear.?Don't leave it up to the users to interpret the meaning of your words.
• contextually appropriate. Rather than writing generalised statements, focus on giving out meaningful and relevant data which links back to your heading and the topic of your document.

Step 5. After completing the previous step, your sections are content-rich, meaningful and discrete. Next, to connect the document's discrete blocks, we need to read the document holistically. When readers will be reading your document, they shouldn't feel a disconnect when moving from one section to another.

Connect the dots, build a story.

For example, in the strategy document, your?"Background"?section should talk about the background of your product and the theme, the current state and the challenges experienced. The following section, "Strategic objectives", should define the strategies to solve the challenges mentioned in the background section. And similarly, in "Guiding Principles", we should determine the principles, rationales and implications that help adapt the strategic objectives defined in the previous section.

Step 6. By now, your document has all the relevant content, and it is well connected. Now comes the time to refine your document with more appropriate words and phrases and fix all grammatical errors. But before you start this step, make sure you timebox each section. Set some limits, like "I will only spend ten/twenty/thirty minutes on this, then move on". Whatever works for you, stick to your limits. Remember,?it's always better to have a less perfect document than not having it.

Refine your document

Step 7. Your first draft is ready. It's time you take a break from writing and then come back to do this last but essential step. In this step, read your document aloud. Reading it aloud will help you find any complicated sentences or words that don't make sense. You might either remove a few sentences, rephrase a few, or add new ones to add more value and purpose to your document.

Along with doing a self-review, you can ask your peers or share your document in a closed group for early feedback. Even timebox this step too. Whether it's a self-review or a review by your teammates, it can become a recurring indefinite process, so it's wise to set a time limit of a day or a week for the review process to complete.

Do a self review and get it reviewed

Step 8: PUBLISH IT!!!

PS: I always follow these steps when I write my documents; I have done the same for this blog as well.

Special thanks?to Ania Wedracki?for helping me through this and improving my skills in writing technical documents.