5 best practices for technical writing

5 BEST PRACTICES FOR TECHNICAL WRITING

Technical Writing is basically writing a clearer technical document. It is simply taking high-level information and processing it into digestible content for a specific audience.Technical Writing can include a wide range of documents like instructions, presentations, web pages, brochures, proposals, press releases, specifications, reviews, reports, newsletters, and so on.

These documents, according to me, can be broadly classified into two types: 1. Internal Documents – Documents that are for internal organization, staff members, or internal project team members, like Development Guidelines, Functional & Technical Specifications for the Development team; Technical Guide for the Support Team; Testing Checklist for the QA Team; Training

Programs for team members; Pre-Release and Release Notes, and Process Manuals etc.

2. External documents – Documents that are public facing are classified under the external documents. 

End-User Documents: Documents like User Guides, Pre-Release and Release Notes, Training Programs, Instruction & Product Manuals.



Marketing Documents: Documents like White Papers, Case Study, Press Release, Reports and Website content.

Yes I know, at first, it may be overwhelming to see so many different types of documents. But each document uses a similar writing process and draws on an established set of skills. If you develop a process, you can apply it to any technical document you are creating.

In this blog, I will be sharing 5 best practices which you can use at the ready when you begin with your technical writing project.

1. Know Your Audience Analyzing your audience guides the intent of writing and determines how complex or how simple the piece should be and how much the content level should be.

Here are a few basic principles that you can follow: 

Identify your target audience – Identify who you are addressing your document to, like – programmers, project managers, executives, designers,

marketing people, testers, end user, support team, and admin team, etc. So, if possible, pick just one target group of people and write for them. 

Know the culture of your audience – Determine what your target audience already knows and what they need to learn. You must also be aware of the ways in which your audience uses documentation, and when. What language does your audience speak-technical, or marketing, or design? What other kinds of documents do they use, and how? Does a paper document make sense, or would a presentation be more appropriate? You want your document to integrate into your audience’s culture, not disrupt it.

Let us see a scenario to understand it better.

For a Mobile Application, while writing a technical specification guide for developers, it will contain functional requirements, non-functional requirements, business scope, technology stack, infrastructure requirements, etc. However, while writing a public-facing user guide, it will only contain Instructions and the User Interface related content for the end customers. So this means for the same application, you can make two entirely different documents depending on the type of audience.

2. Plan your document This may seem obvious but spending time up front on planning can reduce the actual writing time. Create a list of all the tiny actions you need to take towards your goal.

Prepare a schedule to organize below pointers: 1. Collecting Data – Collect appropriate data before starting the documentation so that you know what the user already knows and what you need to tell them next.

Asking questions is an art and if you want to collect data and simultaneously build up knowledge, you need to know WHO to

ask, WHAT questions to ask and WHEN to ask. Then you also need to record the answers from others, so you build up a sort of FAQ database for yourself.

It will be great idea to plan the document skeleton virtually in your mind while you are collecting the information.

2. Drafting – Start writing what you know from what you gathered. When drafting procedures, do a self-review to make sure you can perform each procedure as you have written it.

Above all, keep the user in mind. While preparing, try to predict the questions that may raise in the mind of the user. Users must be able to easily understand and navigate through the content.

3. Reviewing – Typically, a Subject Matter Expert (SME) reviews the first draft and the final draft of the document. Depending on the type of content you are developing, however, you may want the SME to check individual sections or topics.

4. Revising – Now that your first draft is ready, set up a peer review to test the accuracy. Again, make sure the content is presented in a way that makes sense for your audience.

5. Editing – In this phase you need to make sure the language has a logical flow and the content is complete and consistent. Having a second set of eyes on the content can increase both the credibility and professionalism of the entire piece.

Tip: Always start your document on a blank page.

3. Gain Technical Knowledge A technical writer must understand the subject and the purpose of the document.

At first it is required to gather the prerequisite information by –



Studying existing material from the knowledge repository



Interviewing SMEs for KT or any query



Using the product

Simultaneously it is a good practice to search the internet for online videos and other relevant material to understand technical jargons.

Online content and videos will be very useful in the case when you need to prepare a new document from scratch. This will not only help you enhance your technical knowledge for that domain but also guide you to grow in the project.

4. Make it Interactive The writing should be straightforward, to the point, and as simple as possible to make sure the reader understands the process or instruction.

This at times may appear as simply a list of steps to take to achieve the desired goal or may be a short or lengthy explanation of a concept or abstract idea.

Follow the tips below to make your documents visually appealing and interactive: 

Structured – Document formatting is one of the most important elements in readability for end users. A document can be frustrating to read and absorb if it is not structured into a clear hierarchy of information. The simplest way to structure the documentation is to organize it by groups. Use headings and sub-headings, Table of Content, and hyperlinks (internal to the document and/or external).



Typography – Font brings character to the document and varying font sizes can help to draw reader’s attention as well. Also, emphasizing headings, titles, and important takeaways to stand out on the page can be effective.



Color-code your notes – Adding a splash of color to the important topics helps to make the information more readable and easier to retain.



Visuals – Things like diagrams, workflows, flow charts, highlighted notes, and other visual aids are often great ways to associate and remember key concepts.

5. Follow Grammar & Writing Rules When you speak and write, you must put the words in the right order so that people will understand what you are saying or writing. Rules make people feel comfortable.

We have listed down few ground rules for writing: 

Use active voice.



Convert the passive voice sentences to active voice.



Develop at least three strategies to make sentences clearer and more engaging.



Keep your sentences short. Use bullet points and numbered lists.



Develop at least four strategies to shorten sentences.



Create effective lead sentences for paragraphs.



Avoid jargon.



Focus each paragraph on a single topic.



State key points at the start of each document.



Understand the curse of knowledge.



Break long topics into appropriate sections.



Use commas, parentheses, colons, and semicolons properly.



Use terminology—including abbreviations and acronyms—consistently.



Use spell checks to reduce the likelihood of spelling errors.



Use several techniques to detect mistakes in your own writing.

Technical writing is centered on good planning and audience focus.

These tips provide different perspectives and practical methods to accomplish your content goals.

Write to us to know more about our services and next time we speak about how to go about playing it right with your API documentation.