Company In House Writing Guidelines

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. Acronym Standard Definition MCC Master Control Center ROP receive-only printer
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. Do not use a large number of acronyms, especially new ones, in a short span of text. Do not use similar acronyms having related meanings. Do not create "new" acronyms for old terms. Do not give "old" acronyms new meanings. Use "standard" acronyms. If it is necessary to create new acronyms, do it in consultation with others. The DRBDeveloper Review Board is a good starting place. Every acronym, no matter how well known or widely used, must be defined (expanded). For the first occurrence of an acronym in each manual page, spell out the whole phrase, using lower-case letters (except for the specific exceptions described under Capitalization Exceptions) then insert the acronym, using all capital letters, in parentheses. Each time you use the term thereafter, use the acronym alone. Example: ...candidates for being held out-of-service (OOS) when ... Later references to the out-of-service condition use the acronym only: The unit remains OOS until... Do not expand acronyms that are also registered trademarks. For example: ANSI®. 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: Correct - asymmetric digital subscriber line (ADSL) Incorrect - ADSL (Asymmetric Digital Subscriber Line)
Capitalization Exceptions	Names of products are proper names and should be initially capitalized. Along with these, there are other exceptions: Wide Area Telephone Service (WATS) Master Control Center (MCC) Switching Control Center (SCC)
Gerunds	Gerunds are verbs used as nouns. It is an obscure grammatical point, but a logical one, that gerunds take a possessive. Examples: Correct - "The issue is John's being there." Incorrect - "The issue is John being there." "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. Correct - "the unit was taken out of service," Incorrect - "The resulting out-of-service unit is...." 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: Note: Text of note goes here.
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: "If the event occurs one or two times, then...," "A test is repeated 1, 2, or 16 times depending on the value of variable 'w'."
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: Step Action 1. Log on to the development server. 2. Type: getrcview # where # is the RC/V View number (e.g. 8.22). The getrcview tool allows you to search on values other than the view number. Enter getrcview with no arguments to display the other search options. 3. Read the line called Screen Title. The view name will be listed to the right of the arrow. Note 1: On the development server, /home/rctool/bin must be defined somewhere in the PATH variable of your .profile. Note 2: getrcview will default to the current release under development. If you wish to utilize a different release, execute the following command prior to getrcview: export LOAD=<load_number>
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: RLNAME (when referring to the whole relation) rlNAME (when referring to a tuple of a relation) 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: "Either a tuple is missing from the RLNAME relation, or ..." "Either an rlNAME tuple is missing or. . ."
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. For tables: Do not use B, R, or I in the table specification line (example: cB s s). Use \fB, \fR, and \fI as appropriate. Table headers include everything that is printed before the detail lines of the table. This includes any underlines, spaces, or special character lines. Table headers may not exceed 11 formatted lines. Displays (.DS and .DE) are only used if they are surrounding error code tables. Elsewhere, they should be replaced with no-fill macros (.nf and .fi), for example, in a ROP sample. No trailing tabs or spaces at the ends of lines. No tabs in no-fill text (i.e. examples of ROP output). Do not use .B, .I, or .R in the raw files. Use \fB, \fI, and \fR as appropriate. Do not use Information Mapping® macros. All trademarks, registered trademarks, and service marks must be properly identified. Footnotes can not exceed five formatted lines.
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: /usr/add-on/wwb/bin/wwb <filename> > <temporary_file_name> 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. Term Replacement Table Term Replacement bug problem, inconsistency craft user, office personnel domestic U.S. foreign international init initialize (verb), initialization (noun) insane corrupt restoral restore (verb), restoration (noun) Telco service providers
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: Never use a mark in the possessive case. The common name of the service or product may be used in the possessive case. Never use a mark in the plural form. The common name of the service or product may be pluralized.
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.