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 just finished writing our company style guide. I attended two sessions on Style Guides at our Regional STC conference in October and would be glad to "share" that information. As for "where to start," I've appended a text file of the table of contents for my style guide. . . might generate some ideas, questions, etc. Let me know if you'd like copies of the .pdf files from the STC Region 7 Conference. Also, if you have questions, suggestions, or need more info, let me know.
Here's the TOC:
Table of Contents
About this Guide 5
Documentation Goals 5
Who Should Use this Guide 5
Conventions Used in this Guide 6
Future Revisions to this Guide 7
Using Company Names and Logos 8
Official Company Name 8
Logos 8
Terminology 9
Using Eclipse and ZZSoft 9
Ambiguous Words 9
Redundant Phrases 10
Types of Words to Avoid 12
Copyright and Trademark Conventions 13
Copyright Notations 13
Trademarks 14
On-line Documentation Style/Conventions 16
HTML 16
PDF 16
Writing and Editing Rules 16
Abbreviations and Acronyms 16
Admonitory/Advisory Paragraphs 19
Alphabetization 20
Audience 20
Bias-Free Communication 21
Capitalization 22
Cross-References 24
Emphasis 25
Examples 25
Fonts 25
Headings 26
Hypertext Links 27
Hyphenation 28
Icons and Graphics 29
Lists 30
Personification 33
Presenting Computer Elements 33
Punctuation 34
Sentence Structure 36
Spelling 37
Symbols in Text 37
Tables 38
"That" versus "Which" 38
Use of Common Terms 39
Creating Procedures 40
When to Use Procedures 40
Standard Procedure Format 40
Established Procedure Style 40
Avoid Supplementary/Commentary Text in Procedures 42
Identify Choices or Alternatives 42
Use of Action Verbs in Procedures 43
User Interface Design Conventions 45
Eclipse UI Guidelines and Paradigms 48
Appendix 1: Preparing Glossary Entries
Composing a Glossary Entry
Writing a Definition
Formatting the Term
Formatting the Definition
Appendix 2: Index Style
Levels of Entries
Style for Index Terms
Page References in Entries
Cross References
Appendix 3: Supplementary Documents
Writing Tutorials, Demos, etc.
Eclipse Marketing Documentation Conventions
Eclipse Documentation Process
Glossary
Index
Marj Hermansen-Eldard
Senior Technical Writer
ZZSoft, Inc.
>>> "Wigser, Sarah" <Sarah -dot- Wigser -at- CONNECT -dot- XEROX -dot- COM> 12/09 1:07 PM >>>
I have been tasked with devising a style guide for a few departments in my
company. I have seen style guides, in fact I use a couple on a regular
basis. But I am really at a loss for how to start writing a company-specific
one.
Any ideas/words of wisdom would be much appreciated!
