Three top tips for writing clear technical content
Anne-Marie Chisnall | July 4, 2023
Technical writing is sometimes defined as simplifying the complex. Image by Lucas Santos / Unsplash Licence
In a recent Q&A about the Plain Language Act 2022, people asked lots of questions about writing technical content and making sure it is clear.
Many government agencies work with technical topics. They also need to communicate information clearly to members of the public, who may not be subject-matter experts in those topics.
In What is technical writing?, Connie Giordano says:
Technical writing is sometimes defined as simplifying the complex … communicating complex information to those who need it to accomplish some task or goal.
Here are our three top tips for communicating technical information clearly — while meeting the needs of both writers and readers.
First, know your readers and the outcome you want
Who is your reader and what do they understand about your topic? What do you want your reader to do with your information?
It’s one thing to write a paper — for example, to an expert panel of people who live and breathe the topic, and who know all the associated specialist terms. But if you publish the same paper on your website so that it’s available to a wider audience, those readers won’t have the same level of expert understanding.
So think carefully about what will work for that wider audience, and what you can do to help them easily access your technical information. Make sure your key messages are clear, so that your reader can absorb the information and knows what they need to do.
Second, apply the 10 elements of the Write Plain Language Standard
The Write Plain Language Standard works for any type of writing, from annual reports and ministerial briefings to webpages, guidelines, and information leaflets.
The Standard encourages you to use everyday, familiar words and phrases, and to remove jargon and bureaucratic language. For the best result, apply the other elements too.
- State a clear purpose for the document and use a reader-focused structure.
- Include relevant content that supports the purpose.
- Use informative headings to highlight key messages.
- Write short, focused sentences and paragraphs.
- Keep the tone reader-friendly.
- Use layout that supports accessibility and readability.
By applying the 10 elements of the Standard, you’ll clarify your technical content!
Download the Write Plain Language Standard
Third, help your readers with technical terms
Plain language doesn’t mean technical terms are banned — far from it. Technical terms are part of communicating with precision. But, remembering your wider audience of non-expert readers, make sure you give them some extra help to understand technical language.
What can you do to help readers understand technical terms and technical content?
- Include a glossary or add a link to a helpful resource.
- Give definitions in a list or, better still, in the text.
- Use examples or illustrations to help explain terms and concepts, or calculations.
- Provide a plain language summary of a technical document or expert paper.
If a concept is too complex to explain succinctly in your document, say what you can briefly, then provide a link to a more detailed explanation.
Remember to avoid using jargon — words or expressions that have a specific meaning in your profession, but that are difficult for others to understand.
Jargon: how to recognise it, and let it go
Take a look at some inspiring examples!
You’ll get lots of inspiration from government agencies and others who are already doing a great job writing clear technical content. Here are some examples.
A glossary of technical terms
Te Ara Ahunga Ora | Retirement Commission has published a glossary of financial terms called ‘De-jargoning Money’, the result of lots of consultation across the financial sector. Anyone writing content that uses financial terms can refer to the glossary for the industry-accepted term.
A definition written in everyday language
Check out this definition of ‘due diligence’ by Digital Boost (a free government-funded tool to help Kiwi businesses adapt to today and prepare for tomorrow).
Due diligence is one of those things that sounds complicated, so let’s break it down. Basically what it means is reviewing all terms and conditions, and consumer reviews to make sure the company or person you’re dealing with or paying for goods or services, is legit … due diligence is like doing your homework, but for business.
(Digital Boost newsletter, 19 June 2023)
Illustrated guidelines
The Ministry of Health has published guidelines on healthy eating and activity for New Zealanders. Design agency Gusto helped create an appealing booklet that clearly communicates evidence-based recommendations using infographics and illustrations.
The webpage that hosts the guidelines keeps the reader in mind with a summary of the information included in the guidelines, and notes on related resources.
Summary webpage for the eating and activity guidelines
Supporting images and illustrations help to make technical guidance clear and accessible. Image by Gusto Design — used with permission.
A technical policy
WorkSafe’s ‘How we do Duty Holder Reviews’ is an example of a technical policy that uses plain language principles. It won the award for Best Plain Language Document — Public Sector in the 2022 Plain Language Awards. The judges said:
This document is a great example of plain language and good information design. It explains a complicated subject in a simple and clear manner that is interesting to read.
The document has good tone and is clear and simple without feeling patronising.
The headings are particularly effective. They are written in a conversational style, and we can skim them and understand the structure of the document in just a few seconds.
This document is very appropriate for the subject matter and audience. Well done!
WorkSafe’s award-winning policy
An academic paper introduced with a blog post
Write consultants Libby Ross and Corinna Lines worked with Jan Feld to find out if writing quality matters to academics. Dr Feld is a senior lecturer in economics at Te Herenga Waka — Victoria University of Wellington.
They wrote a plain language explanation of the study and its results as an introduction to the forthcoming full paper (also in plain language).
Proof at last? Academic writing needs to be clear too
Want to know more about writing clear technical content?
This blog by former Write trainer Emily Cotlier has lots of great advice on writing instructions.
Three tips for writing instructions
Join one of our interactive workshops on technical writing, covering proven techniques for structuring and expressing technical and complex information in plain language.
Join a Technical Writing workshop
Join a Writing Instructions and Procedures workshop
Read other blogs about the Plain Language Act 2022
Who decides what constitutes plain language?
How will the Plain Language Act 2022 be enforced?
Does the Plain Language Act 2022 affect how you use reo Māori?