7 technical writing tips
At first, what are the types of technical writing. There are many classifications but the most useful one depend on the audience you write for:
- Traditional or professional-oriented writing, e.g. medical research, technical description.
Writing for professionals means that you also must have an appropriate technical background. For example, a traditional technical writer might also be a programmer, pharmacist, engineer. The writer’s professional title may be a strict requirement. - End-user technical documentation, e.g. electronics, consumer products, user Help Guides, Product Manuals.
Readers you are writing for aren’t professionals, and that’s why try to explain things as clear as possible. Remember about the so-called curse of knowledge, a cognitive bias that occurs when a person, communicating with the others, unknowingly assume that they have the same background to understand. The truth is that your readers don’t. And don’t have to be. Avoid specific terms and jargon, if for some reasons you can’t drop it then explain the meaning.
Despite the type of audience, there are still common technical writing tips.
Tip #1
At first, make a plan: identify key materials, relevant details, and basic points you have to mention, mark the presumed chapters and think about the layout of the document. And now, when you know for sure what to speak about in each part of the doc, start writing. It has much in common with drawing: you mark the placement of major elements and then add more and more details.
In general technical writing is not about inspiration but about describing the particular items. So if you feel lost and don’t know what to write further then go back to plan and improve it.
Tip #2
Kurt Vonnegut’s advice was “Write to please just one person. If you open a window and make love to the world, so to speak, your story will get pneumonia”. What does it mean for technical writers: identify who is going to read your documentation and specify your writing for the exact type of person. It helps to use the persona method: imagine a fictional character that represents the most typical user of the stuff you’re writing about. Include features like education, profession, pains, goals, interests, and anything that’s important to identify the user. That helps to understand your reader and prepare more targeted documentation.
For example, this is Mark, he is 25–35 years old, graduated from college, works as a project manager at the small company, his main duty is to coordinate 5–15 people in the sphere of IT, usually run of time, his fear is to lose track of processes.
Tip #3
Imaging that the person you are writing for is extremely tired, exhausted, and it’s already 3 am. Try to write as simple as possible, make it easy to understand. Include step, then in each step add how to find the information for that step. Avoid phrases that can be interpreted in more than one way, get rid of jargon.
Check yourself: after you’ve finished part of the doc, look through if it’s simple enough to be understood by half asleep tired person? If the answer is “yes” then your job is well done!
Tip #4
Your readers are searching for a quick solution. So if it’s possible to describe the subject clearly in 5 words then don’t use more. The same instructions can be conveyed in 500 words or 5000 words, it doesn’t influence total quality at all. The best documentation is the one that is effective for the reader regardless of the word count.
There is no conflict with previous advice, just be detailed enough and avoid adding information that can be skipped without harm. The main thing here is to find balance. So if a particular part of the doc is relevant then let it be, if it’s not then don’t make anyone read it.
Tip #5
The previous points were about the essence of documentation, now let’s speak about its form. Be more visual, use images and screenshots where it’s possible, add arrows, circles, numbers to screenshots to make it even more understandable. This point also provides you with the opportunity to be briefer and keep more useful information in less space. Try to use examples instead of just a bare explanation, that helps a lot.
Tip #6
Try to add more structure to the doc. Break your text into blocks, use interval difference between paragraphs and chapters, highlight certain phrases, mark the headlines, make some words bold or italic — all of it makes text readable.
Use your corporate design to make documentation recognizable and allow it to elevate the company’s brand.
Tip #7
The most obvious and the most skipped advice is reading aloud. Wait! You’re also going to jump it over but don’t. Sometimes what you want to say is so ingrained in your mind that you still miss some of the smaller mistakes.
Instead of a conclusion
It’s always not easy to begin. If you’re reading it, that means you ought to improve your skill. Tips, that are listed here, are helpful, but the most brilliant teacher is an experience. The more you write the better you become. Try to analyze what you like or don’t like in the documents you meet — that also helps to improve your professional level.
And then you’ll succeed.
