These are five tips for technical writing that I believe are helpful for both new and experienced technical writers.
When I started my job with Opera Software in late 2016, my initial tasks were to edit and proofread documents, blogs, and product text. A few months later, I was asked to develop help content for Opera Touch, a new mobile web browser the company was developing. The browser had two features that the product manager anticipated users would need how-to articles for reference. I was thrilled for the opportunity, even though I had never written help content before in my career. No one offer me any tips on how to go about writing technical docs.
This was a sink-or-swim moment in my time at Opera Software. Through trial, error, rewrites, and heaps of scratch paper and notes, I developed a system for composing help content that I carried with me in my career.
I hope the following five technical writing tips will be fruitful for you as well.
Use headers to create a help database roadmap
Starting a new piece of writing can be tough, no matter what the topic or genre is. Mind maps and brainstorming diagrams help to paint the broader picture of your content, while writing out the roughest of rough drafts will spark creativity.
Creating help content for software or online products have the same hurdles you find when writing narratives or articles: you are not sure how to begin, how to finish, and how to fill the inbetweens.
Journaling and “just writing” often spark creative thoughts in me. When tasked with composing help content for a new mobile web browser or time and attendance software, I had to employ the same methods.
Once I understood what the products are and do, I wrote the steps of using the products as H2s and H3s on a word document. The table of contents then served as a guide for me to see the whole picture. It is then much easier to go to the specific task and write the details.
Brevity is best
I love the Internet, and one of the greatest treasures found in the World Wide Web are recipes. I search for recipes because I want a list of ingredients I need to gather and a formula by which to blend the ingredients to create a meal. I do not search for recipes because I want a 1,500 word, ad-laden story about how this perky stay-at-home blogger absolutely loves, loves, loves this totally delish dish.
The same goes for technical writing. Readers want direct answers to their frequently asked questions. I used to bore readers with background information on how and why the company developed a certain feature. That kind of stuff is reserved for blog and social media content. It was better to get to the point of how to use the feature.
(For the record: ignore my anecdote at the start of this blog, as well as the lack of brevity. It doesn’t count here.)
Know your platform
Understand the limits and possibilities of the platform on which you will be publishing your material. If you make grandiose plans for your help content, you best ensure the platform you are using can cater to them.
I had spent weeks building up a knowledge base for a payroll and time and attendance management software on Word. I designed tables, illustrations, and placed images of buttons inline with step-by-step instructions.
When it was time to transfer this collection of how-to knowledge to the company’s help centre platform, I was dismayed to discover that the platform — which will remain nameless for the sake of respect — could not, at the time, display tables or in-line images. This required me to rejig nearly every step-by-step guide I had written, and to dismantle tables and lay their contents bare in paragraph form.
This is all to say that it is best to have a scouting report of the platform onto which you will be uploading your material before you start designing the intricacies and the fancy tables of the content. Knowing your platform may give rise to new ideas on how you can present your content. For instance, you may discover that you can present raw HTML snippets or embed GIFs and videos into your content.
It is okay to be passive
As most writing teachers — and lately Microsoft Word — will tell you, writing in the active voice is preferred over the passive voice. The active voice lends to clarity and ease of reading, and the passive voice is to be used sparingly for variety.
Yet the passive voice lends itself better to technical writing since the focus of the content are the things that are acted upon. In fact, I think the use of the passive voice is unavoidable in such writing. It is preferred, especially when the performer is understood to be the reader.
Download these two free tools to create help illustrations that pop
Help content that is concise and easy to understand is often enough for readers, especially if they are already familiar with the software or product. Yet when you are guiding readers through the use of a program that is new or complicated for them, then you will want to use images and illustrations to supplement your step-by-step tutorials.
Tools like Photoshop, Illustrator, and Sketch are awesome, but also awesomely pricey. All you need are GIMP and ShareX, two free tools that work just as well as the previously mentioned ones.
ShareX is a screen capture application for Windows. You can capture full and cropped areas of your screen, and even record video and GIFs. I filmed an entire online tutorial course for payroll and time and attendance software and accounting software tutorials with ShareX. The pixel-level zoom camera lets you frame exactly what you need.
(For Mac users, I would recommend Snagit or Camtasia.)
The images you capture with ShareX can then be edited and enhanced with GIMP. The freeware software is nearly as versatile as the powerful and spendy Photoshop. While you may not get the photo-editing magic that Photoshop provides, GIMP is certainly enough for highlighting, enhancing, sharpening, annotating, and embellishing your screen captures of the product. Below are examples done using both tools.
If you are wanting more tips about technical writing, or you are looking for someone to help you get started on building up a help centre for your new software product, please feel free to drop me a line.