Documentation Standards Outline Summary

Subject: Documentation Standards Outline Summary
From: Kathleen Frost <kfrost -at- BTSQUARED -dot- COM>
Date: Mon, 6 Oct 1997 09:25:14 -0400

I have received over 100 requests for this outline so I am going to post it
rather than answering each individual message. (I need to spend all that
time working on my own Standards. My boss liked the idea so well, I also
have to write a Programming Standards Guide now.) I hope this is of use
to many people.

Many EMail applications have export features to turn Email into text format
which you can then open as a document in whatever word processing system
you may have. John Posada graciously offered to put it on his site ( ) as well.

I have added everything I could into one outline and added other
miscellaneous topics at the end. You can pick an choose whatever applies
to you. Good luck.

Kathy Frost
KFrost -at- BTSquared -dot- com
BT Squared Technologies, Atlanta, Georgia USA


Purpose of this document

Overview of contents

Table of Contents

Section 1 - Corporate Identity

Chapter 1 - Company Name

How used, trademarks, first occurrence, later occurrences

Chapter 2 - Logo

How used, colors, sizes

Chapter 3 - Documentation Stamps

Draft, confidential, etc. When and how to use, sizes, etc.

Section 2 - <Company name> Documentation Plan


Part Numbers: Numbering documents in a publication library

Chapter 1 - Internal Publications Library

List of docs with audiences

Chapter 2 - Client Publication Library

List of docs with audiences

Section 3 - Style Guidelines

Chapter 1 - Formatting



References to other levels of doc (i.e. quotes, italics, underlines)


Common Usage (ex. Use drop-down menu rather than pull-down menu)

Format of words/phrases (ex. Names of keys, F4, user input in style
Code, etc)

Chapter 2 - Style Sheet

Recommended spelling

Glossary of Common Terms

Online Style Sheet (internet address)

Chapter 3 - General Writing Style Guidelines

Chapter 4 - Glossary

Chapter 5 - Corporate Abbreviation/Acronym list

Section 4 - Online Help Format


Standard RoboHELP templates. Copy from network for
paragraph styles.


General Overview Topic of the Application

List of main windows with jumps to each.

General Topics

Technical Support, Minimum System Requirements, Products List.

Main Window or Tab Topic

Field Level Topics

Procedure Topic

Setting Up Window Types for the Project

?Main? and secondary windows, as type for procedures

Inserting Mini-Buttons

Headings and Sub-Headings


User Input and Code (para: Code, char:Code Text)

Notes Notes style with NOTE in all caps, bold, rest in italics

Cautions and Warnings, Boxed and Centered




Creating bitmaps, convert to x.SHG format to save space, hotspots on
help graphics, taking screen shots

Section 5 - User Manual Format

Chapter 1 - Front Matter





Related Publications, Contact number for ordering

Technical Support Contacts and Phone Numbers

Document Conventions

Chapter 2 - Back Matter




Forms for users to planning user input

Hard copy format

Mirror margins, settings

Odd/even pages

Different first page

Content of headers and footers


Page/chapter numbering scheme

Convert Online Help File to Base Document Instructions

What template to attach, specifics for each project, selections during
conversion process

Create Manual Instructions


Referencing other Documents and levels of documentation

How to format references, initial caps, quotes, or italics

Section 6 - Training Manual Format

Section 7 - Release Notes/Technical Bulletins

Chapter 1 - Release Notes Format

Chapter 2 - Technical Bulletins Format

Section 8 - Internet Site Procedures and Policies

Section 9 - Technical Review Cycles


Define each review cycle, when in development it occurs.

Pre-review editing checklist(s) (i.e. spellcheck, headers and
footers, page numbering, grammar, graphic/caption, update TOC and
index, etc.) for each review and the final version

Chapter 1 - Outlines

Chapter 2 - Online Help

Chapter 3 - Paper Documents

Chapter 4 - Internet/HTML Reviews

Chapter 5 - Peer Reviews/Code Reviews



Appendix A. Proofreader's Marks

Appendix B. Forms Used by Technical Publications

Documentation Services Request Form

Editing Checklist

Pagination Sheet


Examples of other topics to pick and choose from??

Active Voice

Break pages using "Keep Lines Together" and "Keep With Next"
formatting rather than hard page breaks

How to handle caps in hyphenated words

Numbered and bulleted lists, introductory sentence, when and how to
use punctation

Mnemonics/Shortcut Keys Regular text or small caps for Alt+Down,
Ctrl+F4, etc.


Sizing, Callouts, Captions, Tables to list graphics


"Click" use with button

"Select" use with options on a menu, radio buttons, or list box

One or Two spaces between sentences.

Production tasks

Editing check list for each review and final

Department Polices

Using company applications, such as source control software, PKZip,
Bug tracking systems, etc.

Using company policies: i.e., when to back up and how, how to report
problems, how to request hardware or software, off-site storage and

Paper documentation back up. Such as what hard copies to keep, like
technical reviews, during development, and what to keep after

Internationalization issues, such as using "Postal/ZIP Code" in an

Related Publications


Document/Development Life Cycle

* Requirements Phase *
? Business Requirements
? Technical Requirements
? Software / Hardware Configuration

* Design Phase *
? Communications Architecture
? Application Architecture
? Database Architecture
? Database Update Controls
? High Level Design
? Detail Level Design

* Development & Testing Phases *
? System Test Documentation (test cases, scripts, etc)

*Production Phase*
? User Procedures
? Production Support Procedures
? Operations Procedures
? Help Desk Procedures
? Installation/Configuration Procedures
? Turnover Procedures


Standard Phrases,

?.especially for online help. This chapter of the document is still in
its infancy -- I'm learning as I go along. But one thing I have
realised is if you use the same phrases for the same functions, the
user gets a grasp of the concepts far more easily. For example, we use
"This menu leads to options for..." for first-level menus, "Enter the
name/company (etc.) here..." for fields where data entry is required
and a description of the function for function keys.

For example <F4> Del "Deletes the currents setup.." and so on. The
user learns by repetition. They only have to read the opening of the
sentence to know to which part of the screen, menu, etc. you are
referring. It gives your documentation a sameness to it that reassures
the user.


The Role of Technical Publications at [Company Name]

Technical Writer's Mission Statement

Writing Ethically

Writing High Quality Documentation

Services that Technical Publications Can Provide


Writing Style

Defining the Audience

Looking at [Company Name] Audiences




Writing Guidelines

Treatment of Lists

Using References

Grammatical Issues


Common Terms

Font Styles

Other Elements


Editing and Revising Your Work

Starting the Editing Process

Marking the Manuscript

Editing at the Sentence Level

Editing at the Paragraph Level

Editing at the Topic/Heading Level

Editing at the Chapter Level

Checking the Spelling

Using the Grammar Checker to Check Readability

Identifying Writing Style Problems


TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
Search the archives at or search and
browse the archives at

Previous by Author: Need corrected address
Next by Author: Doc Standards, A thank you
Previous by Thread: Re: ADMIN: Observation about requesting assistance
Next by Thread: FWD: New Employee Problems w/ Management

What this post helpful? Share it with friends and colleagues:

Sponsored Ads