Re: style guides

Subject: Re: style guides
From: Marjorie Hermansen-Eldard <meldard -at- ZZSOFT -dot- COM>
Date: Wed, 9 Dec 1998 13:45:22 -0700


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
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



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

Any ideas/words of wisdom would be much appreciated!


From ??? -at- ??? Sun Jan 00 00:00:00 0000=

From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: Re: WinHelp secondary window for window-level help
Next by Author: Re: Comments from the field (rather long)
Previous by Thread: style guides
Next by Thread: Re: style guides

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

Sponsored Ads

Sponsored Ads