Writing Standards
Source for Writing Standards | The primary source for establishing writing standards for documentation comes from the company House Style web page (http://www.company.com/house_style.html). Other documents that are of general help with the mechanics of writing (corporate style standards, usage standards, punctuation, etc.) exist, and you are encouraged to use them. The Documentation Style Guide can be ordered through the company CICCustomer Information Center. You can access their web page at: http://www.cic.company.com. For most questions of mechanics, we recommend The University of Chicago Press, The Chicago Manual of Style. |
||||||||||||||||||
Information to Document | Distinguish between "nice to know" and "need to know" information. Include the "needed" information in the appropriate section(s) of the manual page. The "nice to know" information belongs in some other user manual and is to be cross-referenced by referring to that manual and its manual number. | ||||||||||||||||||
Acronyms - Standard Definitions | Some acronyms and their definitions have been standardized for consistency both within the document set and with usage in the company training organization. These acronyms are shown in the Standard Acronym Table.
|
||||||||||||||||||
Acronyms - Usage Rules | Acronyms occur throughout company documentation. Used too much, however, acronyms cause confusion and interfere with understanding. If you have a sentence containing many acronyms, try to reword the information into multiple sentences if at all possible.
It is sometimes difficult, especially in long manual pages, to be sure that every acronym has been expanded. Read through the final draft copy, scan for acronyms, and then look back for each acronym to verify that it has been properly expanded. This is especially important if you are modifying an existing manual page. You may insert material that contains acronyms that are expanded later in the text. Make the necessary changes so that the expansion only accompanies the first use of the term. |
||||||||||||||||||
Capitalization Rules | The usual rules of English usage apply (initial capital letters on sentences, proper names). The names of components of the switch are not proper names and are not to be capitalized, except when they fall first in the sentence. All acronyms are fully capitalized but expansions are all lower case:
|
||||||||||||||||||
Capitalization Exceptions | Names of products are proper names and should be initially capitalized. Along with these, there are other exceptions:
|
||||||||||||||||||
Gerunds | Gerunds are verbs used as nouns. It is an obscure grammatical point, but a logical one, that gerunds take a possessive. Examples:
"Being" is the gerund, and "John's" must be possessive. |
||||||||||||||||||
Hyphenation | Use hyphens to join elements of a compound word used as a modifier before a noun. Do not use hyphens with the same words used to describe a condition.
There are other situations where hyphens are appropriate to aid understanding, even when they might not otherwise be required by the "rules of punctuation." Consult a standard reference manual for guidance. The following are always hyphenated: receive-only, office-dependent. |
||||||||||||||||||
Jargon | Do not use jargon. A manual page is a formal document, and there is no place in a formal document for jargon. Jargon is slang; it is vague and its meaning is subject to change over time. Use words in common English whenever possible. Unless the information is meaningful to the intended audience, do not mention "subsystems" or other concepts that have meaning only for developers. |
||||||||||||||||||
Line Length | The length of each individual line in the raw file should not exceed 70 characters. Lines that exceed this length can cause problems in generating the printouts for DRB review. The vi editor provides a method to automatically limit the length of lines as they are being entered. |
||||||||||||||||||
Notes | Notes are entered into text as if they are a variable list. The raw file looks like: .VL 4P .LI "Note:" Text of note goes here. .LE The formatted output looks like:
|
||||||||||||||||||
Numbers | Whenever numbers appear in a text string, spell out numbers smaller than ten, except when being used in combination with multi-digit numbers. Multi-digit numbers (such as; 23, 119) are written out in Arabic numerals. If a sentence contains a mixture of small and large numbers, it is generally better to write them all as numerals, rather than as a mixture of numerals and spelled-out numbers. Examples:
|
||||||||||||||||||
Paragraphs | Use paragraph breaks whenever the thought changes. Use the breaks to guide the reader in scanning the section quickly for the important points. Paragraphs of one or two sentences are acceptable. Avoid long paragraphs that contain a jumble of different ideas. |
||||||||||||||||||
RC/V Views | Recent Change views should be referenced by both the view name and view number as follows: RC/V View x.x (NAME OF VIEW) The word "View" is initial caps and followed by the view number. Immediately following the view number is the view name in parens, fully capitalized. To find the corresponding name of the view number, do the following:
|
||||||||||||||||||
Reference to Embedded Elements | The company presents the switch as a single entity, and the customer views it that way. The fact that it contains a processor (the XYZ computer) that the company sells as a separate product must not distract from treating the total switch as the product, not its component parts. Wherever possible, refer to the embedded XYZ computer as the administrative module (AM). | ||||||||||||||||||
Relation References: RLNAME or rlNAME | All relations should be in one of the following forms, depending on the context of its usage:
Relation names are relatively easy to identify because they are often preceded or followed with the word "relation." For example: "Either a tuple is missing from the RLname relation, or ..." which should be rewritten in one of the following ways:
|
||||||||||||||||||
Restrictions | The following is a list of documentation restrictions. This is not an exhaustive list and individual documents can be required to comply with other restrictions unique to that document. Failure to comply with these rules will result in problems converting the files to SGML for delivery.
|
||||||||||||||||||
Spelling and Punctuation | You are urged to run a spelling and punctuation check as a final step in the preparation of every new or modified manual page. The WWBWriter's Workbench software package is recommended. It is available on most servers. Enter:
You can then review the output online in more detail or send it to a printer. WWB is an automated tool, not a magic solution to your writing problems. It cannot always offer the best solution, and sometimes it offers a wrong one. As with any tool, you have to use its results with caution and apply your own judgment. But it can point out possible spelling errors, wordiness, grammar and punctuation errors, and experience has shown it to be a worthwhile addition to any writer's tool kit. |
||||||||||||||||||
Technical Assistance | There are times when you cannot list all of the possible actions to be taken. It is also incorrect for you to make any assumptions about what escalation procedures may be in place in the user's environment. Most service providers have an escalation procedure through their own experts, leading to a company Technical Support Service. Not all service providers use such an escalation procedure. So, you can not assume to impose any structure on the procedures the service providers adopt. In these cases you may tell the users to "...analyze and evaluate the data..." and "take corrective action." But you must never tell the user to "proceed in accordance with local practice" or "seek technical assistance". These formerly standard phrases have been a major source of annoyance with our customers. If it is necessary for the service provider to get more technical advice than what is available locally or through the documentation, a reference should be put into the text pointing to the TECHNICAL ASSISTANCE section of the manual's front matter. Standard wording is: Refer to the TECHNICAL ASSISTANCE portion of the INTRODUCTION section of the manual. |
||||||||||||||||||
Terms | "Manual page" means the entire description of a message even if the description actually consists of several printed sheets of paper or several screens of information. Some terms have been eliminated from the text because the can cause problems when translated into other languages or because of legal issues resulting from union rules. These terms have been replaced as shown in the Term Replacement Table.
|
||||||||||||||||||
Trademark Usage | Company trademarks are a valuable business asset. Careless use or misuse of them can cause legal difficulties, and can even result in their being denied to us. | ||||||||||||||||||
Trademark Usage Rules | The proper name of our product is a registered trademark, and the "registered" symbol, ®, must appear with the product name the first time it appears on a physical sheet of paper. However, because page breaks for paper copy of manual pages may change, the registered symbol needs to be included with each entry of the product name. While some variation is allowed for other purposes, the convention used in this manual is governed by the Documentation Style Guide. This document states that: "The noun used with the trademark is treated the same as any common noun (for example, upper case in an upper case line, initial cap in an initial cap title line, and lower case in a text line)." In addition, the company House Style web page (http://www.company.com/trademarks.shtml) has the following rules regarding the use of trademarks:
|
||||||||||||||||||
Trademarked Names inside Code | It is common practice to use the names of hardware inside code, in such things as relation names, variable identifiers, and as part of input and output messages. While it is commonly done, it is not an especially wise practice, since future nomenclature changes can make the relation name or message obsolete. If you have a choice, avoid using hardware or trademarked names in code and avoid having to refer to them in user documentation. On the other hand, if a trademarked name does appear as part of a code fragment in a user document, it is not necessary to include the ® or TM symbols. |
||||||||||||||||||