A style guide is a set of requirements and guidelines for a documentation project. It provides requirements and guidelines either that are not stated anywhere in general style guides or that contradict requirements and guidelines stated in those general style guides. For example:
In its glory days when its employees were encouraged to plan and define everything, every minutiae, IBM had a corporate style guide that was carefully cross-referenced the Chicago Manual of Style. The section numbers in the IBM style guide mirrored those in Chicago: you could see which guidelines were additional and which were contradictory to Chicago.
Individual product areas within IBM had their style guides: these had the same relationship to the IBM corporate style guide that the IBM corporate style guide had to the Chicago Manual of Style.
Of course, the purpose of a style guide in this technical-publishing context is to enable writers and editors to produce consistent documents as efficiently as possible. A good style guide saves writers and editors from fretting over which is the right style or format for a chunk of text and from wasting time sifting through published documents looking for the answer. A good style guide also cuts down on time-wasting debates and arguments that writers and editors get into concerning what's "right."
What sorts of guidelines and requirements go into a style guide? Here are some examples:
Punctuation and capitalization of bulleted lists
Capitalization of headings
Punctuation of series and
List of words that should never be used
List of words that should be used
Format requirements for certain types of text
Capitalization guidelines
Use of bold, italics, alternate fonts, color
Format and style for example text
Types of content to include or not to include
Content and style of cross-references
Punctuation and capitalization of index entries
Use and style of abbreviations, acronyms in particular
What sorts of guidelines do not go into a style guide? Obviously, standard rules and guidelines that you can find in Chicago or any grammar handbook need not be stated in your style guide. If your writers use electronic templates and styles (tags), you don't have to specify page sizes, margins, fonts for standard textual elements. For example, head1, head2, and head3 all use Arial bold in descending type sizes with specified margins. You don't have state those guidelines in your style. However, you may still want to state a guideline against writers skipping a heading level—for example, going from head1 to head3.
Style guide guidelines are stated as imperatives, for example:
Use lowercase on all index entries except for proper nouns.
Separate the index item and the page reference with a comma.
Do not use Latin abbreviations such as etc., i.e., e.g.
If there is any doubt that your writing team could misinterpret a guidelines, provide an example:
Use initial caps on all main words of field or menu names, even if they use first-word-only caps in the interface. Do not use bold on field or menu names:
Type your date of birth in Date of Birth field, using two-digit numbers for each part of your date of birth (for example, 06/15/53).
If there are certain general guidelines that your writing team constantly forgets or opposes, put them in your style guide (as long as the team as a whole agrees of course):
Avoid passive voice when directing users to do something; use imperatives or second-person ("you"). Use passive voice only when the actor is not the user and is obvious, unknown, or unimportant.
When you have developed the individual guidelines for your style guide, plan an organization and format that will enable your documentation team to find those guidelines easily and rapidly.
Group your guidelines into intuitive categories such as:
Highlighting
Capitalization
Terminology
Italics
Bold
Fonts
Courier New
Times New Roman
Bulleted Lists
Numbered Lists
Lists (Vertical)
Abbreviations
Cross-list or cross-reference guidelines. For example, computer documents often use italics for variables (placeholder text for which users substitute their own text). Consider stating the guideline or cross-referencing the guidelines under headings like "Variables," "Italics," and "Highlighting."
Highlighting
Capitalization
Terminology
Italics
Bold
Fonts
Courier New. See Fonts.
Times New Roman. See Fonts.
Bulleted Lists
Numbered Lists
Lists (Vertical)
Vertical Lists. See Lists (Vertical).
Abbreviations
Here are some example excerpts from style guides:
Corporate style guide
ABC, Inc., Writing Style Guide
Oil Accounting Documentation Standards
User Help System Design Standards
Information and programs provided by admin@mcmassociates.io.