TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
* 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
