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 (
http://www.tdandw.com ) 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


Overview

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

Overview

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

Capitalization/Punctuation

Grammar

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

Terminology

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

Templates

Standard RoboHELP templates. Copy Robohelp.dot from network for
paragraph styles.

Format

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

Styles

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

Indexing

Tables

Graphics

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

Overview

Cover

Disclaimer

TOC

Related Publications, Contact number for ordering

Technical Support Contacts and Phone Numbers

Document Conventions

Chapter 2 - Back Matter

Glossary/Abbreviations/Acronyms

Index

Appendices

Forms for users to planning user input

Hard copy format

Mirror margins, settings

Odd/even pages

Different first page

Content of headers and footers

Headings

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

Tables

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

Overview

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



Appendices

Suggestions:

Appendix A. Proofreader's Marks

Appendix B. Forms Used by Technical Publications

Documentation Services Request Form

Editing Checklist

Pagination Sheet



Miscellaneous

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.

Graphics

Sizing, Callouts, Captions, Tables to list graphics

Usage

"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
retrieval.

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

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

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

Voice

Tense

Tone

Writing Guidelines

Treatment of Lists

Using References

Grammatical Issues

Punctuation

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
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html


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