“10 Tips to Improve Your Technical Writing Skills” was written by guest contributor Sophia Gardner.
Technical writing is a component of many different jobs and it also can be a standalone occupation. It deals with creating functional documents and needs to combine a high level of technical sophistication and understanding with a clear, concise, and coherent manner of expressing it.
Engineers and researchers must be proficient in their communication to share all the great things that happen in the world of science and development, but a professional technical writer must really be a master of this craft because her task is to communicate highly detailed and precise descriptions of technical reality in a way that is understandable to an audience at varying levels of competence.
Writing is much like marketing—it’s about getting messages across and about making people feel positive and enthusiastic about the things you write about. It’s also about making them feel good about you because you were helpful and accurate. If people perceive your writing as bad, they will judge you—and more importantly, the company or organization you are representing. You don’t want that. So what can you do to make your writing better?
10 Tips to Improve Your Technical Writing Skills
1. Remember your audience
It’s true for all forms of writing, yet with technical writing, it’s even more pressing. Who are you writing for? What does your reader need to know? Do they need to first gather materials to work with? Do they need to put on protective gear? How do they switch on the equipment? What should they do first?
Come up with the logical sequence of steps, then you can fill in all the details. It won’t do taking the reader halfway through the documentation and then saying “By now you should have done this and that.” That’s really frustrating. You can give a bigger picture at the very beginning, but make is short.
When you start elaborating on the details, make sure it’s in the order that is appropriate to your particular reader’s context.
You might have very different audiences to cater to with a single document – operators must know how to work with the equipment, job safety officers must know if this equipment matches their industry and company regulations, heads of various departments must know some details relevant to their field, etc. That might be difficult to balance, but usually, you can assume the level of prior knowledge accurately enough to decide on skipping or including the explanation of basic details.
For example, for project management software, it’s better to assume a basic level of technical competence, since people from many industries and with various level of tech-awareness will potentially use it in their work.
2. Know all ins and outs
This is an obvious thing but I’ll put it here anyway. You should be familiar enough with your topic to be able to explain complex concepts and ideas in very simple terms. As Einstein said, “If you can’t explain it simply, you don’t understand it well enough.”
If you feel difficulty writing about something, take a moment to assess whether your level of knowledge is adequate. If you have doubts, do your research, take notes and consult experts, and keep doing it until you feel ready to explain everything to a six-year-old.
“If you can’t explain it simply, you don’t understand it well enough.”
– Albert Einstein
3. Think the structure through
Structure your information in a way that makes it easy to find any piece of it. People often turn to guides when something already went wrong, when they are upset, lost, and frustrated. Precision and structure are the best expression of humanity and kindness in this case.
Try to see a problem that the user is having and come up with lists of tasks they need to perform to solve this problem. You can also group those problems into thematic hubs (getting ready, creating, deleting, managing, etc.) Using -ing forms coveys a sense of immediacy that appeals to users, so that’s a good idea to use them when naming your hubs.
Also, don’t forget that some people will need to read through the entire document, so give your text natural flow. One idea should follow another in a logical sequence. Even when you divide your text into sections there has to be some transition between them. This improves readability and encourages your readers to go through the entire document.
4. Use layout
Your text might be expertly structured, yet without proper layout, it will still be difficult to navigate. Don’t underestimate the power of layout.
It’s not about making your text aesthetically pleasing. That’s also a function, but the function is to make your text more understandable and easily scannable. Employing the right layout techniques, you create a map for your reader and guide them with it.
Bulleted and numbered lists, headers, page breaks, bolded keywords, italicized examples, etc. will highlight the intended points of focus and make your message clearer.
5. Use illustrations strategically
A picture is worth a thousand words. Moreover, illustrations are a nice way to break big chunks of dense text that can be boring and difficult to digest. Use different kinds of illustrations: tables, charts, diagrams, and screenshots to balance out the overwhelming text.
That said, add them only if they add value, not just to enhance your text visually. Remember, your reader will be hunting for a particular piece of information and images are attention grabbers that derail this search. Don’t add something that has little value or is something your reader can do without. Images must justify their position in the document.
Always explain your content – it makes a good introduction to conceptual and abstract stuff. When you add images and schemes, explain what is happening inside the picture, not just “This is a screenshot of such and such dialogue.” Make your explanation short and scannable.
Make sure to crop and highlight the images, pointing out the relevant information and leaving out everything else.
Tables should create visual hierarchy, compare the data and help your reader to interpret findings. If not, they have no business being there at all.
6. Use examples
Examples keep your writing tied to reality and this is crucial since technical writing deals with practical things. If you are writing an online help or a disaster recovery doc, then every issue within the text is going to begin with a scenario of things gone wrong.
Yet even for other types of documents try to refrain from being too theoretical. If you are writing a manual and list things that might lead to malfunctions, explain situations in which such things may happen, what are signs of malfunction, how should control panel/indicators/blades look like when everything is done properly. Add visuals if necessary.
7. Improve searchability
Two things that can dramatically improve the searchability of things your readers will look for are the table of contents and index.
Think of your table of contents as of the master list of tasks. Your user should be able to scan through it quickly and easily to find the information they need. Also, don’t make it too technical and ramified. Try to restrict yourself to three levels maximum, otherwise, you make it too overwhelming for your reader and it defeats the entire purpose of the table of contents, which is providing a roadmap.
Depending on the length of your document, creating an index can also be very helpful. People often search for particular keywords and terms. Those words might not be in the software itself, or anywhere in the table of contents. This is a great way to tie words and phrases your readers might expect with the precise technical terms you have actually used.
8. Make human connection
Your text is a bridge between technology and human users. Always remember that humans will read your text. Avoid sounding robotic. Make the style conversational – it doesn’t mean less precise or fraternizing. You don’t have to put jokes there. Just be human.
People rarely like to be referred to as “the user”, so writing in the second person will humanize and make your text easier to read and process (e.g. “Before you start working, place the pad on your left-hand side).
Also, use present tense and active voice whenever it’s possible and keep things simple. Your audience may range across different comprehension levels and making your information as accessible as you can is important.
Ask for the style guides upfront to ensure consistency across all the documentation.
9. Revise and test
Every type of text needs several rounds of revision. This doesn’t only include spellcheck and hunting for grammar errors. Try to step away from your text for a day or two. If this task is urgent, at least allow yourself several hours between writing and final edits. By spacing out your editing sessions you make it easier to spot inconsistencies, redundancies, and gaps.
After you are satisfied with your document, it’s time to test it. Don’t test your documents yourself – it must be someone else. Ideally, a QA specialist that tests your docs against the live system.
Iterate on your text one more time (or several times if needed) based on the feedback your testers gave. When you have a finished, polished version, delete all the other drafts to avoid data pollution.
10. Seek feedback
One is never too good to learn and improve. One thing you can do to identify areas needing improvement is to ask for feedback from both your coworkers and your clients.
Do they find your documents helpful? Do they understand what you are trying to say? Is everything clear? Do your docs answer their questions? Is there anything they don’t like?
They are also more likely to spot any reoccurring patterns in your writing that aren’t strictly necessary and do not add value to the text—things you may be blind to yourself.
Remember, negative feedback and constructive criticism are both an opportunity to work on and improve your skills. Keep a notebook of your mistakes and the things you’ve learned and never stop perfecting your skills!
About the Author:
“10 Tips to Improve Your Technical Writing Skills” was written by Sophia Gardner, a freelance writer for various online platforms that provide essay writing help. Her humble copy might be found, among other things, on appliance packages, software manuals, and MMO games FAQs. She now leans more towards journalism but a background in technical writing has taught her how to get stuff done so it doesn’t need redoing.
- How to Be a Better Ally to Your Female Coworkers
- Top 10 Best Mac Apps for Modern Engineers
- 10 Tips for Writing a Great Engineering Resume
- Getting That Engineering Resume Past the Robots
- 7 Ways Engineers Can Improve Their Writing Skills