Technical writing is a challenging field. Technical writers must be able to not only provide instructions and descriptions to readers in an easy-to-understand manner but also do so in a way that requires the least amount of interpretation possible. It’s not an easy task by any means, and it can be very difficult for writers who try to tackle the job from home. However, if you are ready to take on this challenge as a part-time or full-time gig, here is some advice on how you can achieve good technical writing.
How Is Good Technical Writing Achieved?
Be Specific
Good technical writing is all about being specific, not general. When writing a user guide, for example, rather than saying “click here,” you should say “click the green ‘Start’ button located in the upper-right corner of the page.” This is especially important when documenting code. Rather than describing a function as “a piece of code that does X,” you should say something like “the function processor() runs when the order button is clicked in the ‘Orders’ section of the dashboard.” Get specific every time you can and your audience will thank you.
Use the Right Words
The right words are important. Beyond just targeting specificity, they’re also a tool for eliminating the need for footnotes and clarifying meaning. If you are documenting a function, it is important to use the right terminology. There are differentiating factors that, when used in certain ways, can cause a function to perform a different task. For example, the “select all” button on a word processing program doesn’t actually select all of the text in the document. Instead, it selects all of the text in the current selection. The “select all” function in a programming language, however, does select all of the text in the document. When documenting, it’s important to use the correct terms for each identifying factor. This can help eliminate any confusion that may arise from one function performing a different task than its cousin function.
Be Narrative
Good technical writing needs to be at least a little bit narrative. In other words, it needs to have some human emotion behind it. This is particularly true if you’re documenting a procedure that requires users to feel a certain way. A technical manual may describe how a user should feel completely relaxed and at home while using the product. Studies show that the manner in which language is written and delivered can have a significant impact on how readers feel. If you were to write a user guide that is void of emotion, readers will likely feel much when they read it. By adding a little bit of narrative to your technical writing, you can help readers feel more relaxed, welcome, and at home when using your product.
Be Consistent
Good technical writing also needs to be consistent. If you clearly document something one way in one place, you should do your best to make sure it is clear in all other places. If you say that a certain button is used to start an order in one place, you should also say this in the user manual. In a way, consistency is a natural extension of specificity. If you know exactly what you want to say in a given situation, and you’re consistent with your word choice, it’s likely you’ll be consistent with other word choices as well.
Be empathetic with your audience
Part of being specific, narrative, and consistent is being empathetic with your audience. As a technical writer, you may have a general idea of who your audience is. You may even have a name and face for that audience member. But you are never truly able to step into the shoes of your users. In order to truly get to know your audience and write in a way that resonates with them, you’ll want to do a little research on their end. By actually using the product yourself, you’ll get a better feel for how your audience members will interact with it. You’ll also be able to identify specific pain points that, if you eliminate or alleviate them, will make your product all the more useful.
Don’t be afraid to revise and rewrite
Good technical writing is never truly finished. It is important to remember that, as you document, there is always room for improvement. If you aren’t happy with your writing, if it doesn’t flow, or if you think it could be more clear, don’t be afraid to revise and rewrite. You may also find yourself in a situation where you must write multiple pieces of content and you need a way to tie them all together. Perhaps you have a series of short training videos that all use the word “click” to indicate the viewer should click a button, but no two videos use the word in the same way. You can use italics or bold typeface to show the variations in word choice. This not only helps you avoid using conflicting words but also allows you to link together with your work and reinforce concepts across multiple pieces.
Learn to code and understand your platform
Finally, you should also strive to understand the platform your technical writing will be delivered on. If you’re writing user guides, you should try to understand the code that powers your product. If you’re able to write code as you go, you’ll be able to fully understand how each piece works. This will help you create work that is more effective and efficient. If you have the ability to sit in on developer meetings, you should do so. This will help you better understand your platform and the language that is being used. This can also be helpful when you are tasked with creating documentation for the developers.
Tips On How To Achieve Good Technical Writing
1. Use proper grammar and spelling
Your code is only as good as its documentation. That is, if it’s impossible to understand your code, it won’t matter how well it functions. Your readers will never be able to properly implement the new features into their programs if they can’t understand them. That’s why you must use proper grammar and spelling when documenting your code. After you’ve written the code, sit back and read over it a few times to make sure you’ve used proper grammar and spelling. This simple step can make a huge difference in your code’s readability.
2. Proper Code Formatting
When you write code, you’ll notice that each language has its own format. Engineers have developed this formatting over time to make the code easier to read. Although formatting isn’t nearly as important as the actual code itself, it can help engineers understand your code better. You don’t have to follow a specific format, but you should at least understand the basics. If your code is formatted incorrectly, other engineers will have a difficult time reading it. This can lead to confusion and frustration among readers. If you use a specific language, take the time to research what the proper formatting is. This can make a big difference in your documentation.
Conclusion
There are many challenges facing technical writers, but it can also be very rewarding. However, if you are trying to achieve good technical writing, it is important to remember that writing is a skill that can be improved with time and practice. If you are ready to take on this challenge, there are many ways to improve your writing, from expanding your vocabulary to reading as much as possible. While it will take time, you can achieve good technical writing.
FAQs
Should I write in English?
Yes. In general, you should write in English, as it is the most common language used around the world. It will also help to make your work more accessible to a wider audience (it is easier for non-native speakers to read and understand)
Should I use technical jargon?
No. If you don’t know the jargon, then it’s best if you don’t use it. Remember that technical writing is meant to be read by someone who isn’t familiar with the software or technology being used. You’ll find that your audience will appreciate your work if you write in plain language that they can easily understand and follow along with.
What are the best technical writing resources for beginners?
The best technical writing resources for beginners are the ones that you find yourself using, such as your dictionary and thesaurus. But if you’re not sure where to find these resources, a quick internet search should provide you with plenty of options.
