Style Guide in Technical Writing

As technical writers, you are often asked to create or refer to style guides? Why? Style guides can help in improving document quality and in standardizing document presentation. For example what is correct - 5 or five? Style guides can help you decide this. Let’s understand the basics of style guides.

What?

Style Guide is a set of standards that highlights the preferred writing style, punctuation, spelling, and formatting used for various publications by an organization. You can refer to industry-accepted style guides or create your own in-house guide.

Why?

• Consistency – Ensures consistent and uniform look of all publications, thus enabling readers to seek information with better ease and speed. For example, if you are using American English, you will make sure you write “analyze” and not “analyse” throughout your document though both are grammatically correct spellings.
  

• Easy Writing and Editing – It is easy to create or review a document if the writing rules are already clarified. You can refer them any point in time to make sure you are using the correct format.
  

• Effective and Fair Writing – Adherence to style guide helps to create neutral and effective publications regardless of each author’s personal writing style. For example, you will follow the capitalization rules as specified in the style guide instead of your own way.

Examples:

• Microsoft Manual of Style for Technical Publications (MSTP)
• Sun Style Guide
• Chicago Manual of Style
• Elements of Style
• Apple Style Guide

Technical Documents

Technical Writing involves creating a wide range of documents that varies across organizations. These documents are created using various tools like MS Office, FrameMaker, RoboHelp, Adobe Creative Suite comprising of Photoshop, InDesign, Flash, and so on. Some of these technical documents are:

1. User’s Guide: Companies that offers products or services need to have user guides to explain how to use the product/service. The Guide contains detailed description of product/service features and instructions to use them.
2. Online Help: The growth in online media has popularized creation of Online Help by companies. The Help provide assistance on using a particular product/service.
   
3. Installation, Reference and Troubleshooting Guide: Companies needs to familiarize the users how to install or repair their product or software. This document provides steps to install and troubleshoot the product or software.
4. Release Notes: Companies create Release Notes to familiarize the users with new features, enhancements, fixed issues and known issues of the product or software. These are publications distributed along with product in the development or test state. These are also created every time a bug is fixed or an enhancement is made on the product.
   
5. Technical Advisory: This document describes an issue, its cause and work around.
6. Marketing Collaterals: Companies create marketing or sales document to market and promote their product or services. Common examples of marketing collaterals are business proposals, white papers, datasheets, sales brochures, flyers, catalogs, posters, and presentations.
   
7. Training Materials: Companies require training their employees or external customers. These are publications created for use in self-paced training or classroom environment. Common examples are tutorials, workbooks and instructor’s guide.
8. Miscellaneous: Occasionally, companies need other type of writing intended for publication done for them. For example, documents like newsletters, technical reports, resume, press releases, etc. are created by technical writers.

Tools in Technical Writing

Technical writers create documents in various formats like electronic publishing, print, online help, etc. The various tools used to produce technical documents are described below.

Publishing Tools (Microsoft Word, FrameMaker) - Microsoft Word is actually the most popular tool for publishing in spite of its bugs and limitations. It is easy to use, review, and make changes. But with larger documents (more than 500 pages), Word behaves a bit inconsistently and may get corrupt. Here, FrameMaker creates more stable documents. Styles are very consistent and rigid in FrameMaker and it can handle large amount of text and graphics.

Help Authoring Tools (RoboHelp, Epic Editor, AuthorIt) - With the increased use of the Internet, users have become more accustomed to using online information. Online help is searchable and helps the users to resolve their problem or query easily rather than going through pages and pages of manuals. Help Authoring Tools like RoboHelp, Epic Editor, AuthorIt are used to create online help.

Template Designer (Indesign, PageMaker, QuarkExpress) - Template designing tools are used for creating documents that require a flexible layout or strict typography demands. It is easy to create and design datasheets, whitepapers, brochures, solution sheets and other marketing and technical documents using these template designer tools.

Image Editor (Photoshop, SnagIt, CorelDraw, Illustrator) - Graphics are an important part of any document. As rightly said "a picture is worth more than words to say." Image editors are used for image designing, capturing, cropping, morphing and all sorts of image editing.

Web Design Tools (Dreamweaver, FrontPage) - Web design tools are created to deliver content to end users in the form of web pages. You can create both static and dynamic web pages using web design tools.

Screen Recording Tools (Camtasia, Captivate) - Recording tools like Camtasia and Captivate are used to create product demos, engaging simulations, scenario-based training, and randomized quizzes. In addition, it doesn't require programming knowledge or multimedia skills.

Multimedia Tools (Flash, Max 3D) - Multimedia tools are used to create audio and video content. Multimedia tools like Flash and Max 3D can be used to create interactive animations and demonstrations.

These are some of the basic tools used in technical writing. Other tools like Teamsite, Lectora, Visio, and so on are also used to create content and graphics.