Technical Writing Best Practices

|

There are many opinions about what good technical writing is.

Some focus on the importance of consistency and style, and others on the quality of the writing. In every case, technical writing should always be clear, concise, and easy to use.

ProEdit’s technical writing services reflect the industry’s best practices, such as:

Analyze the audience.

David A. McMurrey, professor and technical writer, considers the audience “the most important consideration in planning, writing, and reviewing a document.” To write effective documentation that suits the users, we must understand their needs. In other words, ProEdit doesn’t create a 300-page manual when a quick reference guide will do.

Write reader-friendly documentation.

Technical writing is full of complex information. ProEdit writes documentation to your audience’s readability level. Many methods exist to test readability, including the Gunning’s Fog Index and the SMOG Index. Microsoft Word also includes a Flesch-Kincaid readability tool to check the readability of a document.

Use active voice.

It is commonly held that passive voice is acceptable in scientific and technical writing. However, overuse of passive voice, or use of passive voice in long and complicated sentences, can cause readers to lose interest or to become confused. ProEdit uses active voice to ensure that your readers and users clearly understand your documentation.

white mechanical pencil

Use advance organizers.

In technical writing, an advance organizer (also called a “jump list”) is a bulleted list at the beginning of a chapter that provides an overview of the chapter. David Ausubel, a psychologist who developed advance organizers, states in his Subsumption Theory, “The most important single factor influencing learning is what the learner already knows.” Advance organizers help users process and retain information based on what they already know.

“Chunk” your documentation.

ProEdit breaks your documentation into smaller portions using bulleted lists, shorter paragraphs, and cross-references. We chunk your documents according to topics—one topic per chunk. Chunking keeps the readers’ attention, providing them space to stop and absorb what they’ve read.

Provide adequate white space.

Too much text crammed onto a page intimidates readers and turns them away. In technical writing, we always use white space around the text to break up pages. Too much text can tire the eyes.

Use cross-references to related information.

Technical manuals can be quite bulky, especially when information is repeated unnecessarily. ProEdit uses cross-references to link related information that is described elsewhere in the document and is not essential to the current discussion. In online documentation, we provide adequate hyperlinks to cross-reference related information.

Use step/action tables.

Step/action tables provide a practical way to separate procedural steps from other descriptive information. This is a very important aspect of information mapping. Procedures contained in step/action tables are easy to read and follow, increasing document effectiveness.

Create a quick reference chapter, section, or guide.

A quick reference summarizes the most common user procedures, which is very helpful to users. TVs, DVD players, and computers are often equipped with a “Getting Started” guide. A quick reference helps your users get started without having to comprehend a large amount of information beforehand.

Create a glossary of terms.

Think about all of the times that you wish you had a glossary while reading something. We can create a glossary of definitions of important terms in your documentation.

Create comprehensive indexes.

An index helps users find the information they need in the documentation. The number of pages of single-column index should be approximately 10% of the total length of the document.

Edit the documentation.

Then, edit it again. The importance of editing cannot be overstated. Inconsistency in technical writing affects credibility and the user’s perception of the documentation.

About ProEdit

Since 1992, ProEdit has been a leader in the technical writing industry. We strive to offer the highest-quality technical writing services at a competitive cost to clients in Atlanta, across the U.S., and abroad. We pride ourselves on producing large volumes of technically accurate information in a short amount of time.

Connect

Leave a Reply