Ten Commandments of Technical Writing

The goal of any technical writer is to prepare technical documents that are relevant, useful and accurate to the target audience. Sadly, we have no rules carved in stone to help us reach this goal.

But here are 10 basic guidelines that would help us produce better documents:

#1 Never Make Assumptions. When in Doubt, Clarify it.

Inexperienced (and sometimes experienced) technical writers often fall into the trap of making assumptions about the document’s scope or the project’s scope itself.

For instance, our first source of information about a project is the Subject Matter Expert (SME). SMEs often tend to use jargons during discussions. As technical writers, we should never hesitate to stop the SME and ask for clarification if something is unclear.

Also, not every technical document could be written in the same way. Therefore, before you start writing, it is important to understand what you are writing (e.g. user guide, installation guide, API document), whom you are writing for (e.g. developers, novice users, client) and the medium of publication (e.g. print, desktop,mobile).

#2 Work With a Plan – Never Sit Down to Write Without a Plan

Just like any other task, writing technical documents requires planning. Before you start writing, create an outline of the topics that you will be covering, know the naming convention that you will be using, the way in which you will be organizing content and your document’s design aspect.

Also, be prepared to accommodate some unplanned changes as you may discover that you need to make a few additions when you start writing or at the time of revising.

#3 Use File Naming Conventions

You may say that you don’t need to follow file naming convention as you have no difficulty in keeping track of your files. But how about finding a file 3 years from now?

What if, you have worked on a project along with another technical writer a few months ago and now your boss wants to review the changes that were made.

Would you be able to locate such files effortlessly? Vague, inconsistent file names may be easy to remember now but in the long run they will create confusion and mix-ups. It is important for all technical writers in an organization to decide and stick to a file naming convention.

As a rule, filenames must be meaningful, must indicate what the file contains, and must be easy to search later. The following are some examples of some good and bad file names:

Good FilenamesBad Filenames
Productname_Userguide_Author.docProductname.doc
Productname_Installation_Guide.docProductnameInstallation.doc
Productname_Installation_Guide_version.docUserguide_author.doc

#4 Use Templates & Styles

Have you ever considered the amount of time it takes to just format a document from scratch? If you have a well-designed template in place, you already have predetermined heading & paragraph styles, page layout, front cover, TOC, glossary, header, footer, index elements. This gives you more time to focus on your content.

When you are working as a team, templates allow you to set standards. Using styles in your template is just as important. Let’s say your client doesn’t like a subtitle font, normally you would need to change the font on each subtitle all over your document.

If you use styles, you only need to modify the subtitle’s style element and all the related instances would be automatically changed. If your organization doesn’t have a template already in place or if you don’t use style elements, I highly recommend you to create them for any content that you use regularly.

#5 Write Clear Instructions

Now here comes the trickiest part. If you are unfamiliar with the product that you are documenting, you may not be able to organize your content in the right order.

On the other hand if you are too familiar with the product, you may be tempted to skip a step or combine a few steps as it may seem too obvious. As a general rule, every action that the reader needs to perform to complete a task should be documented.

If you have a long procedure (15-30 steps), break it into multiple tasks.

# 6 Use Screenshots and Videos in Moderation

When you need to express a complex idea, it is best to include relevant screenshots or videos in the document. When used moderately, visual aids speak volumes.

But if used liberally, screenshots and videos tend to distract and annoy readers. Take into consideration factors such as disk space, bandwidth, and your audience’s internet connectivity when deciding on the amount of visual help you need in the document.

#7 Insert TOC, Cross-References, Index, Captions the Right Way

The main reason for using a publishing software or a help authoring tool is to ensure that content is easier to manage in future. But, some inexperienced technical writers add table of contents, cross-references, index and captions manually.

This process is prone to make your document outdated very soon. To keep things manageable, always insert these items using your publication software.

#8 Use Active Voice

In active voice, the subject of the sentence performs action whereas in passive voice the subject receives the action. Almost 99.9% of sentences in any technical document are written in active voice.

This is because sentences written in active voice are clear, direct and less wordy.

#9 Document Revisions

Before you publish a document for the first time, add a revision number and a revision log. For every significant change that you make in future, update revision number and add a short description of the changes that you are making in the revision log.

Usually revision number is two part (e.g. version 1.0) with the first part referring to the version of the application, and the second part referring to the version of the document. It is placed on the title page and in the footer.

Revision number Description
Version 1.0Product version 1 and Document initial version
Version 1.5Product version 1 and Document revision 5
Version 2.2Product version 2 and Document revision 2

#10: Proofread

Even the most experienced writers misspell words and make grammatical errors. Therefore, no matter how confident about your writing skills, you should always proofread at least 5 times before you show the document to someone else.

Also, to make sure that you have all the facts right about the product, you must ask the SME to go through the document. It is also better if you could have a co-worker proofread your document as it is easy to see mistakes in other people’s work but so hard in your own.

So, what according to you are the best practices in technical writing? Share your thoughts in the comment section.

Leave a Reply

Your email address will not be published. Required fields are marked *