How To Write Effective Technical Documentation: Newbies Edition
I was introduced to the process of writing technical documentation quite abruptly. As soon as I got assigned the task, I tried looking it up on Google and it kind of confused me even more. I kept thinking, “Sooo….what do I write??”. Hopefully, this will help the newbies into technical documentation to overcome the confusion and shed some light on all the relevant points.
WHAT SHOULD I KEEP IN MIND?
Let’s first get the basics out of the way by discussing the absolute necessities of a technical documentation in brief:
- Understanding level of the target audience
Before you start writing your documentation, you need to keep in mind who is your target audience. This is a general rule for any written piece, however, it plays a much more crucial role in technical documentation.
The tone used and the information provided both will shift drastically according to the intended reader group. It will approach developers and maintenance personnel differently.
You cannot include much details about the code behind the product if this documentation is meant for the maintenance personnel. On the other hand, if it is meant for the developers, they need to know exactly what is going on with the programming underneath. Every time a new developer takes the seat of the old one, he or she will be reading through this documentation to understand the whole architecture and workflow.
2. Points hierarchy
There should be coherence in the way you lay down your points. The order of these points or headings must make the whole reading experience a smooth ride for all your readers. So before starting to write the doc, first scribble down on a spare sheet what points need to be there. Then put them in numbers and figure out the right hierarchy among them. This will make it easy for you to write, as well as make it easy for the audience to comprehend the written material.
3. Simplicity of language
Since English is taught and practiced all around the world, any company would prefer their technical documentation in English. However, if your company follows a different route, you can choose to settle for another language.
In case of an English documentation, the language needs to be sophisticated enough for official use but not difficult enough to seem confusing for the readers. Simplicity is the key to an effective technical documentation.
4. Necessary illustrations
A picture is worth a thousand words. Include all required illustrations to clearly explain the complex architecture or to present the possible user interface of the respective product. While you still need to provide somewhat of a description describing the image, such graphical presentation will never go amiss in a technical documentation.
WHAT SHOULD I IGNORE?
There are certain aspects you need to ignore for composing a proper technical documentation. Here are the two which troubled me the most:
- Word count limitation
For those of you who are used to freelance writing, word count plays a big role in crafting every new write-up. It becomes so much of a habit to constantly check the word count with the shortcut keys, that you almost don’t notice yourself doing it after a point. If you are switching to a corporate job, you must get rid of this habit. It doesn’t matter how many words you technical documentation is. Just write the essential points in order and explain each briefly.
2. Marketing tone
Before getting a full-time job, I was mainly a freelance writer creating content marketing pieces on a daily basis. So evidently, my writing tonality used to reflect the perspective of a “salesman” rather than someone just sharing knowledge or experience.
If you come from the content marketing background as well, remember to be conscious of this habit. Read out the paragraphs you wrote today for the technical documentation and see if it has any advertising or promoting tone. One of the easiest ways to mark such tonality is the presence of superlative adjectives like “the best”, “the easiest”, “the most convenient” etc.
So far I have been working on the technical documentation of several official projects of Invariant Telecom. This company develops software solutions to different contemporary issues including digital financial transactions and ride-sharing facilities. Head over to our Medium page to find out more such articles and write-ups.
