Wed, Sep 27, 2017
9 Technical Writing Tips Every Writer Needs to Know
Technical writing takes high-level details and explains them clearly and concisely to an audience.
While the result of technical writing is clear, succinct and simple, the process can be the opposite. The technical writer’s challenge is to transform complicated information into an accessible document. To meet this challenge, technical writers use different strategies.
This article will provide you with a selection these distinct, action-oriented strategies to improve your technical writing.
1) Create a Persona
The crux of good technical writing is writing for your audience. The audience needs to be defined in the document planning process and then considered at each step of the writing process. Technical writers know that a tech-savvy boss needs different information about a product than a 73-year-old grandmother.
After identifying your audience, refine it further by creating a persona. Imagine the exact person who will be reading your document.
The persona will be obvious if you are writing for a known person, such as your department supervisor. For other documents, the persona can be fictional. Assign your reader a specific age, gender, educational background, career, a story for why they are reading the document, even a hobby. Instead of writing for a theoretical audience, write for a specific, albeit fictional, person.
The more accurately you can imagine your reader, the more accessible your writing will be for them. Instead of wondering if the wording is right for the audience, write and review the wording with this persona in mind. It will be obvious whether or not the text is right for your reader.
2) Beware of Scope Creep
Good technical writers keep in mind the document’s goal at each writing stage. The goal and scope should be clearly outlined in the initial document planning.
During the planning and even the writing process, document content can grow. Technical details are not isolated. They are built on previous developments, and you may want to include supplemental information or additional user instructions. Colleagues may suggest valuable background information or data.
Some extra details are useful. Too many details will cause the scope to creep.
As technical writing strives to be succinct, scope creep creates unnecessary work that ultimately produces a less valuable document for the reader. If you feel the scope needs to broaden, return to the goal. Evaluate if that content is really necessary. Cut it or if necessary, consider separation through appendices and even an additional document.
3) Writing Should Be Easy
If you’re thinking ‘writing is always difficult for me,’ writing is probably not your real problem.
Writing should be easy because the planning process was thorough. The planning process should take up to 50% of overall document preparation time. All key materials, relevant details, and the audience will be captured and organized. The result is your complete document in a condensed format. Writing simply fleshes out this compact version.
If you’re unclear of how to phrase an idea while writing, reflect on your audience and how they would want to read it. If you’re not sure if a data set should be included, refer to your mind map to see if it fits within it. Any writing question can be answered by a complete planning process.
If the writing is difficult, stop typing and return to your plan. There is at least one aspect of the planning process that needs more development. Once you have a thorough plan, only then should you start to write. And it will be easy.
You may be interested in our other article: 87 Business Writing Tips
4) Be Timeless
A technical document is your contribution to posterity. That’s right, you are passing on technical knowledge for readers now and in the future.
Most technical writers focus on today’s audience. While very important, these documents often serve future readers, too. A site assessment may not be read again for 30 years until the property comes up for sale. Software instructions act as the basis for the future manual of an updated version.
To write timelessly, always include dates and timelines where relevant. Avoid including time-dependent or temporary information. If you must, explain its current context for future readers. For example, a health and safety report references current legislation. The act is carefully identified so that it can be differentiated from future revised codes. Your document should be clear and comprehensible now and 20 years from now.
5) Use Attributions
Good attributions are efficient. They allow the reader to reference relevant details without including the information directly. The readers who need that additional information can easily find it, while others can continue on in the document without being buried in background information.
See references as a tool for maintaining a concise and valuable document for your audience.
6) Use Global English
English is an international language. Writing technical documents in English allows them to be broadly read and shared. However, many readers will be non-native speakers.
In order to accommodate all readers, use Global English. This style of English is logical and literal which makes it more easily understood. It has a strong overlap with the technical writing principles of precision and clarity. In addition, writing globally means being aware of content that can difficult to understand or simply misunderstood. For example, avoiding idioms and the subjunctive, as well as being careful with words that can be both a noun and verb (e.g. display or guide).edX supports learners across the world and follows a very useful guide to Global English.
7) Forget the Word Count
Some writers race to a word count, seeing it as the goal marker. In technical writing, word count is a poor judge of completion.
Technical writing should be concise. The same instructions can be conveyed in 500 words or 5000 words. The better instructions are the ones that are most effective for the reader, regardless of the word count.
Use word count as a general guide, not a rule. Never force words onto a page meet a word count. If you can write the same idea in fewer words, it’s better for the reader.
8) Be Humble
Writing is an iterative process. Through good planning, thoughtful writing, and constructive feedback, you will grow and improve your technical writing skills. Each review offers its own lessons.
Be welcoming of feedback from supervisors, peers, and experts. Learn from mistakes, confusions, and comments. Each review session offers an opportunity to grow as a writer. Be humble and accept these educational opportunities.
9) Use Graphics to Illustrate
Graphics can help illustrate your message. In technical writing, the goal of graphics is to help convey information not act as decoration. In our online technical writing course, we teach that graphics should be focused on the reader. Poorly designed graphics can confuse readers and do more harm than good. To learn more about adding graphics to your documents see our article on the topic.
Technical writing is centered on good planning and audience focus. The above tips provide different perspectives and practical methods to accomplish these goals.
About the author
Tom specializes in technical writing and is particularly interested in analytical and financial writing, as well as synthesizing strong executive summaries. He holds a B.A. in Business Administration and English from Reed College, and a M.A. in Communications from the University of Colorado. He has successfully supported our clients from Boeing, FedEx, and the US Army.