Tips to Edit Technical Documentation
by Bradley Nice, Content Manager at ClickHelp — all-in-one help authoring tool
One might think that technical documentation emerged only after the industrial revolution when most technical devices came into existence. But if we look deeper, we see that the drawing is considered one of the earliest process documentation. Or, rather, its varieties that have come down from antiquity. First people used the walls of the caves, the stones to carve the drawings, and even the earth. The birth of construction drawings dates back to when people built a dwelling or storage room for utensils or livestock to survive winters. They developed a lifesize plan with primitive accessories right on the ground and erected buildings on them later.
At all times, there was a need for drawings: in Egypt, Babylon, and ancient Greece, a system of standards emerged in ancient China. By the 15th — 16th centuries, standards for the caliber of weapons appeared. In general, the basic regulatory documentation during the Ancient World and the Middle Ages developed the standardization of industries and processes.
Technical documentation refers to any document that clarifies the application, function, or creation of a product. But in reality, it’s not that easy to explain something about a new product as it sounds. Not all of the tech documentation reaches the aim to be as understandable to the reader as possible. It demands a lot of work with content: planning, interviewing experts, writing, editing, and revising.
Good writing comes down to editing. Here are some tips for efficient editing:
- Gather feedback and revisions. Try to get a second opinion on your content whenever possible.
- Break out your style guide and follow its rules. The style guide should be brief and well-organized so that you could find the answer promptly.
- Edit the documentation yourself or take it to a technical editor who can make sure the language has a logical flow and is consistent throughout the entire content.
- Create a checklist for document finalization. Write down the things that usually escape notice and should be considered for each review. For that, take notes of what other people spotted during editing your document. And always go through this checklist before you submit anything for review. If you see an error or something that should be changed, don’t forget to update this list.
- Get more practice. Practice is a key to any activity. If you want to get a hand in editing, do it more often.
- Use online services. Such services as Acrolinx, Language Tool, or Grammarly help fish out style inconsistencies, grammar mistakes, and mispunctuation.
- Edit one document more than once. You may catch things the second time that you missed the first time. Read your content 3–4 times forward to grasp the substantive problems and then a couple of times backward to catch the style errors. It works to look at the words in non-logical order, and they will jump out at you (i.e., if you used “Select” instead of “Click”). Make each pass as different as possible from the others, on-screen or on paper, in the workplace or some other location, focusing on content or style.
- Use the Read Aloud feature to read the text out to you. It’s sometimes easier to spot errors when listening to the words rather than reading them. It’s a matter of information perception.
A job of a technical writer that creates new content is to have a deep understanding of customer workflows and products. However, editing is maybe a slightly lesser but still important part of that job. Because a highly polished document reflects the professional image of an organization.
Have a nice day!
Bradley Nice, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors