22 Mar Technical Writing Tips
Seven Tips to Nail Down Technical Writing
– Sunita Vyas
The goal of Technical Writing is to help users understand complex products and tools therefore flowery language is not required. The writing should be clear, simple, and succinct enough for the reader to understand the information relayed in the document without any cumberances.
In this article, I am sharing a few tips that will help you write with clarity , be to-the-point and improve your technical writing skills.
1. Know Your Audience
The crux of any technical document is its audience. While writing the information, keep in mind the people who are going to use this information. For example, a tech savvy person with years of experience in the IT field will have different perceptions than a person who is not initiated in this field. Similarly, writing the documentation for a mobile app will be different from writing the manual of an aircraft. Accordingly, the readability, complexity, level of explanation etc will differ depending on the product and the target audience. The best practice for writing user-friendly content is to think of an imaginary user, the age group, domain, and why the product is being used. This will help one write in a specific manner.
If you are not convinced about your document, find someone from the team, who is not aware of the product or feature. Now ask them to understand the product/feature with the help of your document. You will get fair feedback points from the perspective of a prospective user.
2. Gather Information before Writing
In Technical Writing the writing part is the last action of the flow. Before writing anything, you need to gather information, verify the details (which is very crucial), think of user scenarios and finalise the flow of the document. Although these actions are not actual writing, they make your writing more effective, readable and solid.
At least 50% (if not more) of the technical writing is the non-writing part, which makes the document complete and much more effective. So, start writing only when your writing plan and flow is thoroughly ready, and your fingers are ready to follow your mind.
3. Set long term goals for the document
Most of the technical documents are written for passing on technical information. The information is saved for future reference. When a product or functionality is built, the entire team would be thorough with it and they will remember only the main functionality and not the in-depth information. Years later if someone wants to know about the product/feature in detail, then the written document is the only source to get the complete information and know the whys and hows of the feature.Therefore your document should not be specific to current time, it may be used after years, when no one remembers what was actually built. It is good to keep the document generic and mention the date of creation. Try to avoid scenarios which are temporary.
4. Word Count: the last worry
For technical writing where the purpose is to make the user understand the features, word count is the last thing that should come to your mind. The same thing can be written in 10 words and 50 words. However, the best way to write about a feature is to explain it enough so that the reader can understand what you are trying to say and keep it short enough so that the user doesn’t have to struggle to find the actual information.Keep it short or detailed, but let it be readable, useful and helpful for customers. You may skip some obvious things but cover the aspects where the user will need the help.
5. Be Polite
A document does not only provide the information of the product but also indicates the tone of the writer. A user will only need the help document, when stuck or some information is required to clear the doubts or to know what should be done next. In that case, the document should help with enough information and not blame the user or sound condescending. This is also applicable in writing the error messages, where the user is not able to perform an action and needs help.
6. Don’t be Limited to Writing Only
Graphics illustrate the information with ease, in an effective way. For the Technical domain supportive screenshots, GIFs, videos, flowcharts or other visual materials to describe the main content should be provided. This will create a greater impact. Always keep in mind that the visual content is added to convey the information more easily so it need not be decorative. Make sure the graphics are focused on the user’s needs and highlight the areas that require the user’s attention.
While adding graphics, try to keep the quality as good as possible as the poor-quality visuals only confuse and spoil the document rather than doing any good. On the other hand, good quality content will not only make a good impression but also help the users understand things quickly and clearly.
7. Keep it Structured
Unlike other forms of writing, technical writing focuses a bit more on how you present the information to the user. The order of the information should be logical, for example, think of what should be kept first, what should be the sequence of information, which topic needs more explanation, and which can be told in limited lines.
Cramping all information and expecting the user to make sense of it is not a good idea. The overall flow of the information and transition of one topic to another should be clear and smooth. It should clearly emphasize the important things that need more attention.
To sum it up:
Technical writing is centred on good planning. It needs your attention before you start writing the document. Proper planning and structuring of documents and appropriate use of visuals will not only help you write clear and relevant content but also make the document user-friendly.
About the Author
Sunita works as a Technical writer in Mumbai. She is a Computer Applications graduate and has a Masters in English. She is particularly interested in Reading and Writing and is thus fortunate in synching her passion and profession into one.
Read Other Articles of Edition 3 (March, 2021)
- Quality Resume Guide by Mohan Raghuram
- Using GitHub for Authoring by Anitha Rao
- Winner : TWT 1st Anniversary Article writing competition by Mridula Pradhan
- A Tribute to Tech Writer’s Tribe by Serena
- Poem and Painting: In Love by Nupur Pattnaik
- Painting: Musings by Mridula Menon
- Story time: Spin a Yarn by Farheen Banu