Best Practices in Technical Writing

Mridula Menon, in the first session of this workshop, shared her insights for technical writers to manage their projects efficiently. In this session, she has shed light on the key attributes that can help technical writers to deliver their responsibilities timely and effectively.


It was mentioned in the earlier session that the impact of any delay from the technical writer’s end can cost a fortune to the company. Hence, in this session, she has chalked down how to get started on the right foot as a technical writer, right from the early stage of one’s career.


Build rapport with stakeholders


One of the key challenges faced by technical writers is the communication gap between them and SMEs. There are scenarios where there is no response when a technical writer tries to reach out to them for information on the product. This is a sheer functional obstacle as the writer is not able to access the required information.


These obstacles are often heard of in the industry as SMEs are not bound by KPIs to provide the information. Moreover, the focus is on the rolling out of the product, which brings down the documentation process to an overhead.


Before you face such cases, you should:


  • Introduce yourself to your stakeholders formally over mail.
  • Mark your presence in the organization by introducing yourself to the senior management.
  • Keep your LinkedIn profile updated to showcase your experience and connect with your colleagues.


Research and development


Whenever a technical writer finds himself stuck due to functional obstacles, he should plan time management by accounting for all the phases of documentation. It should be followed by the revision of the plan. For this planning, the focus should be also on the availability of the point of contact.


The technical writer should invest a major fraction of the time in preparing for the documentation. He should try and get through every document that is already available with the organization. It helps in understanding the standard and requisites of the documentation process. It is so because as a technical writer, it is imperative to understand the product application before writing.


During the research phase, one of the best practices is to create doc tickets against every dev ticket. This way, you will have a better understanding of your responsibilities while adding ample information before you start documenting them.


After understanding the product, document requirements, and dev team’s routine, a meeting can be scheduled or a questionnaire with relevant questions can be mailed to the POC. The workarounds might differ for writers; however, building a foundation based on thorough research and understanding the availability of the SMEs should precede the interview process.


First draft


80% of your time should be allocated to research for laying the foundation of the technical document. It is only after extensive research that the first draft should be created. The right timing for the first draft is highly crucial. Without thorough research, a technical writer might be running in a loop between writing and researching in bits and pieces.


If a technical writer has completed the following, it can be considered a good time to start drafting the document:


  • Recorded demos
  • Undertaken training and gained product knowledge
  • Asked relevant questions and received answers for the same


Characteristics of a good first draft


The first draft holds an important place in the entire documentation process. Therefore, the need for doing it right is inevitable. Following are some of the parameters to ensure a premium quality first draft:


  • Created a review process by adding relevant people.
  • Gained hands-on experience of the product in the staging environment and explored the features to be documented.
  • Performed usability testing and shared suggestions on microcontent and microcopies in the product to make it intuitive for users.
  • Used standardized doc format from the team based on the type of the document.
  • Used global variables for product and company names.
  • Re-used pre-existing content whenever possible

Respect deadlines


Technical writers need to get their drafts reviewed and incorporate changes. Therefore, it is advised that they account for enough time for these activities when chalking out the plan. This, in turn, helps them to meet deadlines.


Furthermore, if there are any changes in the user interface of the product, the same must be incorporated in the screenshots used in the document. After the final changes are made to the document, the document should be shared with stakeholders for review. Some authoring tools allow sharing of preview links which make the review process convenient. For any kind of review, it is a good practice to keep 2-5 days buffer time for incorporating last moment changes, if any.




Every technical writer goes through his/her own journey while delivering documents. However, the underlying functionalities remain the same for everyone. Lack of information, unavailability of interviewees, strict deadlines, etc. are some of the challenges faced by almost every writer during his/her career. Therefore, getting over these challenges in the early stage of a career can open growth avenues for technical writers. The practices of building rapport, research, time management, etc. ensure a high growth curve for technical writers while minimizing hiccups for them.


For any queries, services, or training in technical writing, talk to our team!  


We have a team of experienced experts for meeting your technical writing demands!


Author: Ruchi Rai, Technical Writer, Metapercept Technology Services LLP

Leave a Reply