GrammarPhile Blog

10 Best Practices for Writing and Editing Technical Documents

Posted by Phil Jamieson   Feb 14, 2019 7:00:00 AM

technical As technology and science become more pervasive and important in our everyday lives, expertly edited technical documents will become more and more in demand. They’re important to businesses, organizations, and consumers alike.

Whether you’re a novice or you’ve written and edited technical documents for decades, here are 10 best practices you’ll want to keep in mind.

1. Know Your Audience and Write Exclusively for Them and to Them

When writing or editing technical documents, it’s essential that you first understand your target audiences and their backgrounds and preferences, and that you conduct research and collect data about them.

For example, some things you’ll want to consider:

  • whether your document is aimed at marketers who are new to your organization
  • whether you’re writing a user manual for common consumers with little to no experience with your technology platform
  • whether you’re writing a manual for experienced coders who already use your technology platform on a deeper level

Essentially, it’s imperative that you understand your audiences’ demographic information and backgrounds, and that you cater your technical content to suit their needs and preferences. Otherwise, it will be impossible or challenging for them to understand, and it will not end up being helpful.

Also, be sure to use “you” and speak to your audience directly in your technical documents and provide plain and simple actions for them to take. Basically, remember to always provide your audience with helpful information in a way that’s easy for them to follow.

2. Organize and Outline Your Technical Writing Before You Write

Create easy-to-follow outlines for your technical documents so that you can organize technical data into chunks of information that are easier to write about and that are easier for your readers to grasp. For example, you can organize your technical information by using steps, chapters, categories and subcategories, tabs, color-coded systems with a key, etc.

Also, if you’re writing or editing technical documents with a lot of detailed and researched material, make sure that you have all your research, information, data, graphs, charts, studies, survey results, etc. well organized and that you know when, where, and how you’re going to use them in your technical documents before you start writing. Be sure to include glossaries, indexes, appendixes, etc. as needed.

Your document should be organized in an easy-to-follow sequence. For example, you wouldn’t explain how to install software on a computer if the computer still needs to be assembled, and you wouldn’t want to discuss how to manage customer data if that data hasn’t been captured yet.

3. Consider Each Document’s Layout Before You Write

Once you’ve developed an outline and organized the research and other materials you’ll need for your technical document, you’ll want to consider the layout of the document. You’ll want to make sure that your images will appear the way you want them to appear and where you want them in the text. And you’ll want to determine your margins, columns, spacing, fonts, etc.

Also, you’ll want to make sure that your documents can be viewed online across the web, and that they will be accessible across different platforms and devices if you’re going to share them electronically with your audience.

4. Always Insert Images, Videos, Data Visualizations, and Other Visual Aids

Technical documents should always contain helpful visual aids, especially in our current world of big data. So be prepared to create, acquire, and insert them into your technical documents as needed. For more insight into criteria for effective graphics and the benefits of graphics, read Graphics in Business Writing, Technical Communication.

5. Be Concise and Use Plain Language

A technical document should always be practical and to the point, because it’s supposed to serve a specific purpose and be helpful. Don’t use frivolous adverbs or adjectives, complex language or sentence constructions, or unnecessary punctuation in your technical documents. And don’t use a string of acronyms that are never defined or that are unnecessary, or words that require your readers to keep a dictionary nearby in order to understand what you’ve written. For example, don’t write something like “Decision-makers will want to use this information to potentially actualize their customer data to boost ROI.” Write this instead: “Use this information to put your customer data into action and to boost your return on investment.”

Technical documents should also be written in the active voice most of the time, because the active voice makes writing clearer and more concise. For example, you wouldn’t write “After the ‘enter’ button is clicked, a box with a red background will appear, which will require the ‘start’ button to be clicked.” It would be better to write “Click the ‘enter’ button.’ Then click the ‘start’ button on the red box that appears.”

6. Remain Consistent

When writing or editing technical documents, be consistent in your word choice, style, layout, etc. And always use a parallel structure. Otherwise, you might end up confusing or alienating your readers, which is the opposite of what you want to do.

Imagine the confusion that a reader will experience, for instance, when you call an implement a “screwdriver” in one section of your manual and a “hand tool” in another. Or if you break down one section of your manual into easy-to-follow steps, while the other sections in the manual contain long, dense paragraphs that are difficult to read through.

7. Remember That You’re a Human Writing for Other Humans

While you want your technical writing to be clear and concise, don’t forget that you’re a human writing for other humans. Don’t let your technical writing become convoluted with odd industry jargon or saturated with acronyms that have no real meaning to your audience. Just write directly to your audience and include visual aids, footnotes, and tips when it’s helpful to them.

8. Always Have Others Edit Your Work and Provide Feedback

To verify that your technical documents are clear, concise, and easy to understand, have others review them and provide you with feedback, preferably before the documents are published or shared with your audience. Others will be able to tell you if certain visual aids don’t make sense, if your layout is hard to follow, if you’re missing a step or an important section, etc.

Better yet, have someone from your target audience read your technical documents first because they’ll be able to tell you exactly what in your documents doesn’t make sense to them, as well as what in them made the information you wrote about clearer and more engaging.

9. Stay Focused on the Purpose of Each Technical Document

Above all else, as you’re composing and editing your technical documents, don’t forget why you’re creating them in the first place.

  • Is it to help new customers better understand how to use a technical platform so that your customer service reps don’t have to field as many phone calls and emails?
  • Is it to help researchers conduct an experiment or a study?
  • Is it to help marketing employees learn new strategies and methods?
  • Or is it something else?

Also, be sure to complete multiple rounds of edits and reviews on each technical document. First check documents for usability and comprehension, then basic grammar and spelling, then industry style, then conciseness.

Remember that a technical document’s layout, style, visual aids, terms, etc. all depend on its central purpose.

10. Test the Practical Usefulness of Each Technical Document

Editors and those who review technical documents should always test the information that’s included in them. For instance, if a technical document is a guide to building a piece of furniture, then the reviewer of that guide should actually build the furniture first. Or she should shadow someone else who’s building the furniture.

If you’re a technical writer or someone who regularly reviews technical documents, we’d like to hear any additional tips or best practices you like to follow as you work. Please share them with us in a comment below.

 

Click to download e-book

Topics: technical writing, technical editing

Subscribe to Email Updates

Sign up for our emails!

Sign Up

Search Our Blog

Recent Posts

Posts by Topic

see all