Users gravitate toward visuals

In my initial days of working as a technical writer, I was advised not to include screenshots of the proprietary software anywhere in documentation. The rationale was that the images could land into wrong hands and competitors would be able to scoop up the features we were adding to the software. That was 2004.

Today, practically no firm can afford to be secretive about their product. With more and more solutions being built around the web, visual aids have become the norm.

When I say visuals, I’m referring to all kinds of visual media such as pictures, diagrams, data charts, infographics and video tutorials.

Even if a user is tech savvy, he or she will immediately gravitate to visuals. The reason behind this is simple: a good visual reduces the sense of cognitive overload. It allows the user to more easily take in information i.e. if the visuals illustrate concepts clearly.

In other words, the fewer details to process, the less the working memory has to sift through the material.

Documentation topics are interconnected

Making a request to one documentation topic often requires the technical writer to adjust other topics as well.

Simple Example:

When a new feature is added to a software product, there may be multiple guides that need to be updated. First document needing updating could be the product’s user-manual. Second document could be release notes. Both these documents are made available to users of the product. Third could be code samples.

Changing one topic can set off a cascade of other needed edits across the entire documentation set.

In summary, a technical writer must grasp the product as a whole to be able to integrate the new information into a larger documentation set.

Therefore it’s not just an ability to write that matters. It’s also the ability to integrate information into a larger, coherent whole that makes the role of technical writing unique, valuable, and challenging.

Technical Writing Best Practices

“The fundamental purpose of scientific discourse is not the mere presentation of information and thought but rather its actual communication. It does not matter how pleased an author might be to have converted all the right data into sentences and paragraphs; it matters only whether a large majority of the reading audience accurately perceives what the author had in mind.”

— George Gopen and Judith Swan  (The Science of Scientific Writing)

1. Analyze the audience

Audience is the most important consideration in planning, writing, and reviewing a document. To write effective documentation that suits the users, we must understand their needs. There is no point creating a 200-page manual when a quick reference guide of 20 pages will do.

2. Use active voice, short sentences.

Use active voice in scientific and technical writing. Long and complicated sentences can cause readers to lose interest or to become confused.

Also, avoid use of jargon unless the reader is familiar with it. If we must abbreviate, we define the term in its first occurrence, and put abbreviations in parentheses. Example: Software Development Life Cycle (SDLC).

3. Use advance organizers.

Use bulleted list or a table of contents (TOC) to provide advance reference. Providing such information helps reader navigate back and forth between different, relevant topics.

Use cross-references to link related information that is described elsewhere in the document and is not essential to the current discussion. In online documentation, use adequate hyperlinks to cross-reference related information.

4. Balance text and other forms of content.

Use appropriate diagrams, pictures and tables to support the written text. Remember: A picture is worth more than a thousand words. 

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.

5. Choose the right format for distribution.

Different formats are available for storing and distributing technical guides to readers.

Most common forms are MS Word (.doc or .docx), PDF and HTML. Some prefer to use Microsoft Compiled HTML Help which is a Microsoft proprietary online help format. (It consists of a collection of HTML pages, an index and other navigation tools. The files are compressed and deployed in a binary format with the extension .chm, for Compiled HTML.)

Drawings can be in .vsd format. (VSD is a file extension for a vector graphics file format used by Microsoft Visio. VSD stands for ViSio Drawing. Microsoft Visio is vector-based software used to create diagrams and flowcharts. To view a VSD file without Visio installed, Microsoft provides the Visio Viewer.)

Other formats can used depending on reader’s convenience and preference. Example: certain embedded video files and powerpoint slideshows can be accessed by user anywhere using a web browser.

6. Review

Remember: Writing is a process.

Good writing doesn’t happen right away; it requires planning, drafting, rereading, revising, and editing. Learning and improvement requires self-review, peer-review, subject-matter expert feedback, and practice.

Inconsistency in technical writing affects credibility and the user’s perception of the matter at hand.

Before starting any technical writing project, Brandfocal Consulting ( discusses the purpose, audience and format in which the documentation will be made available to the readers.