1. Know your audience
Written communications are most effective when they are targeted and personal.
Build your writing around the needs and interests of the user of your technology product.
Most technical documents – blog articles, white papers, manuals, reports, brochures are written for many readers, not just an individual. You may not know the names of those readers, but you need to develop a picture of who they are – their job title, education, industry, and more importantly how they interact with your product.
Sometimes, you need may need to write one topic in multiple flavors to suit different audiences.
2. Know the subject
Before you start writing, take a moment to assess your own understanding of the topic at hand. If you have doubts, do your research, take notes and consult subject matter experts.
If you are writing a software install guide, take out the time to actually install it on you machine. This will help you write with the end-user in mind.
3. Plan structure and layout
Poor organization stems from poor planning. Just like a computer programmer would never think of writing a complex program without first drawing a flow chart, a technical writer must not start writing a user manual before creating a rough outline that spells out the content and organization.
- One topic or idea needs to follow another in a logical sequence.
- Divide your text into sections and use appropriate transition between them.
- Use bulleted or numbered lists, headers, page breaks, bolded keywords, italicized examples, etc. to highlight the intended points of focus and make your message clearer.
Doing the above improves readability and encourages your users to go through the entire document.
4. Use pictures, situations and examples
Use relevant illustrations: tables, charts, diagrams and screenshots to balance out the text.
Include situations where things may go wrong and how to correct them.
Bonus Tip: Be concise
Concise documents convey meaning using the fewest words possible without sacrificing meaning or clarity.
To achieve conciseness, eliminate empty/wordy phrases (there is/are and it is). These are considered to be indirect phrases and tend to be unclear and wordy. Direct statements, on the other hand, are clear and concise.
“There are 25 employees who have already expressed interest in corporate leadership program.”
“Twenty-five employees have already expressed interest in corporate leadership program.”
- S&P 500 companies - February 7, 2023
- Technical Writing: Definition and Purpose - February 2, 2023
- What industries do Technical Writers work in? - February 2, 2023