Table Of Contents
Appropriate Use of Language
This chapter provides guidelines for using appropriate language in Cisco documentation.
This chapter contains the following sections:
If a Cisco product contains accessibility features for use by persons with disabilities, or requires the use of assistive technologies, the associated documentation must describe those features in a prominent location.
Bias-Free Documentation Policy
It is a policy of Cisco to treat all persons with respect—regardless of race, color, ancestry, national origin, age, sex, citizenship, veteran status, marital status, sexual orientation, physical or mental ability, religious creed, or medical condition. Language or graphic elements that offend others violate our business philosophy and our company policy.
Avoid terms that may show bias with regard to gender, race, culture, ability, age, sexual orientation, or socioeconomic class.
Our philosophy toward our customers extends to our indirect relationship with them through documentation and other written and online material that we deliver to customers.
All material written or developed for internal or external use, and prepared for hard copy or online delivery, must be free of offensive or suggestive language, graphics, and scenarios. Editors who see questionable terms can insist on their removal if necessary.
As professional communicators, we must judiciously scrutinize material for appropriateness. We must exercise our best judgment in the use of questionable or obscure terms and flag as inappropriate any language, graphic, or scenario that can damage or otherwise compromise the reputation, good name, or profitability of the company. Writers, editors, and managers must work together to ensure that our online information and publications are free of any potential for embarrassment or grounds for claims of harassment.
For further information, see "Bias-Free Communication" in the Microsoft Manual of Style for Technical Publications.
Cisco IOS Software Release Naming Convention
When referring to a specific Cisco IOS software release, write "Cisco IOS Release 1x.x" or "Cisco IOS XE Release 1.x.x." (The release number increments with each future release.) The words "Cisco" and "Release" are required—do not write "IOS 1x.x" or "Cisco IOS 1x.x."
When referring to a previous release, write "earlier than Cisco IOS Release 1x.x." When referring to a subsequent release, write "later than Cisco IOS Release 1x.x."
Company Names, Product Names, and Trademarks
Use the following guidelines for company names, product names, and trademarks.
Treat company names, product names, and trademarks as single entities. To keep these terms together, place a nonbreaking space between the words. Do not hyphenate the words or separate the terms from each other.
CORRECT ...the test conducted by
Cisco Systems, Inc. ...
INCORRECT ...the test conducted by Cisco Sys-
tems, Inc. ...
Domain Names and IP Addresses in Documentation
Do not use valid or potentially valid domain names or IP addresses in customer documentation, including examples, command output, and sample configurations. Inadvertent use by customers of valid domain names or IP addresses can interfere with network operation, compromise network security and privacy, or conflict with intellectual property rights.
The following sections describe domain names and IP addresses that are safe to use in Cisco technical documentation:
Note Ask your illustrator to change any valid domain names or IP addresses in screen shots, network diagrams, or other graphics to the safe values described in the following sections.
Tip Be sure to use approved IP addresses and domain names in examples for public distribution. Make use of the information in Using Documentation Approved IP Addresses, Domain Names, and Telephone Numbers in Networks and Software Development Documentation (EDCS-609990). Use these guidelines and share them with your development colleagues.
RFC 2606 reserves the top-level domain .example for use in documentation or examples of code. The second-level domain names example.com, example.org, and example.net are also reserved for use as examples.
IP Addresses Reserved for Documentation
RFC 3330 assigns the address block 192.0.2.0/24 for use in documentation and examples of code.
Note The /n notation means that the first n bits of the subnet mask are 1. In other words, the first n bits of the IP address range define a subnet and do not change. For example, in the block 192.0.2.0/24 the first 24 bits (three blocks of eight, represented as three decimal numbers separated by dots) do not change. This subnet therefore extends from 192.0.2.0 to 192.0.2.255.
IP Addresses Reserved by Cisco
Cisco has acquired three blocks of IP addresses that are reserved for documentation. These addresses allow writers to show complex network configurations. Each block includes a subnet. If you use these IP addresses in documentation, you must also include the subnet mask.
Private IP Addresses
RFC 1918 provides a group of IP addresses that are never assigned publicly and are not routed through the public Internet. The same pool of addresses can be used within any private network (a network that does not communicate with the Internet or with other private networks, or communicates only through gateways that translate the IP address). You can use these IP address ranges for hosts that do not need access to the Internet.
Address Block Starting Address Ending Address Approximate
Number of Hosts
IP Multicast Addresses
RFC 1112 defines the address space for IP multicast addresses, which are generally safe to use in documentation because they cannot be reserved. IP multicast group addresses range from 126.96.36.199/8 to 188.8.131.52/8.
The Loopback (or Localhost) Address
By convention, most systems assign the IP address 127.0.0.1 and the name localhost to the loopback interface that allows a client and server on the same host to communicate with each other over TCP/IP. You can use the 127.0.0.1 localhost address in Cisco documentation.
The IPv6 Reserved Prefix
RFC 3849 sets aside the IPv6 address prefix 2001:DB8::/32 for use in technical documentation. Addresses within this prefix are not routed through the public Internet.
To allow you to show complex network configurations, the IPv6 documentation prefix allows many different networks, subnetworks, and hosts. The following table shows three examples of networks within this prefix and a host address on each network. The table uses the following standard notation:
•An IPv6 address consists of eight blocks, separated by colons.
•Each block contains four hexadecimal numbers (16 bits).
•Leading zeros within a block can be omitted.
•A double colon (::) means that two or more consecutive blocks of 0000 have been omitted. This notation can be used only once per IPv6 address. The number of blocks omitted can be calculated from the number remaining.
•A slash followed by a number (/n) means that the number of bits indicated do not change. For example, /48 means that the first 48 bits (three blocks) do not change.
•The minimum number of bits that can be specified with /n is 32 (two blocks).
Use the following guidelines to avoid sexist or gender-specific language:
Human Characteristics Attributed to Technology
Generally, do not apply human characteristics of thought or feeling to software and hardware. For example, avoid using such verbs as think and expect to describe computer functions.
To avoid using the passive voice, describe a product performing an action if possible.
EXAMPLE The router recognizes the IP header information.
Jargon and Slang
Jargon is the technical terminology of a special activity or group. Jargon can be difficult to translate clearly and meaningfully to an international audience. Avoid using jargon unless it is technical terminology that is defined in your document.
Slang and colloquialisms use informal, nonstandard vocabulary. Do not use slang or colloquialisms in your writing.
See also the "Writing for an International Audience" section.
Names and Passwords
Do not use the full names of real people in examples. Additionally, do not use valid usernames or passwords, including forms of "Cisco," in examples. Instead, use username1, username2, password1, and password2.
Past, Present, and Future Tense
Project Code Names
Code names are words used internally to identify Cisco projects.
Caution Do not use project code names in public documents. Confirm that code names do not appear in filenames, configuration files, or other published software examples.
Humperdinck route processor
Cisco Performance Routing Engine 2 (PRE2) route processor
Use the following guidelines when referencing URLs in your documents, regardless of where the URLs appear (including text, procedural steps, and tables):
•Include the name of the protocol—for example, http://—in all URLs.
•You can include a URL in running text or place it on a separate line, at the discretion of writer and editor.
•If you include several URLs in a row in running text, use normal punctuation between the URLs (for example, commas) and at the end of a sentence (a period).
•If you place a URL on a separate line, provide an introductory phrase or clause, and end it with the appropriate punctuation.
•If a URL is very long, place it on a separate line. If it does not fit on one line, format it by inserting a forced return (Shift-Return) between elements, following these guidelines:
–Break a URL immediately after a colon, slash, or double slash.
–Break a URL immediately before a period, hyphen, underscore, question mark, pound sign, or percent sign.
–Break a URL either before or after an equals sign or ampersand.
–Do not break a URL that contains a hyphen immediately after the hyphen.
–Do not insert a hyphen to break a URL.
Verify any live website references in your document before publishing the references. In addition, keep the following points in mind:
•Do not use any references to the Cisco intranet (wwwin.cisco.com).
•Because of liability issues, do not include references to live websites of other businesses in Cisco documentation.
Writing for an International Audience
Because Cisco documentation is distributed worldwide, you must consider certain localization issues. Use the following guidelines to write appropriately to readers around the globe. For further information, see the "International Considerations" section in the Microsoft Manual of Style for Technical Publications.
For information about the Cisco Translation Services team or its projects, contact the translation coordinator by sending e-mail to the doc-translation alias.
Cisco is a global company with offices and sales forces throughout the world. In many nondomestic markets, Cisco faces fierce competition from local and international competitors. In these markets, the accessibility and comprehensiveness of user content are critical to our success. Some of the Cisco user content is translated, some is not; but with the web, users from around the world can easily access all public Cisco content. Therefore, it is particularly important to our globalization efforts to develop all user documentation for an international audience.
Writing for an international audience requires clarity, consistency, and awareness of international variables, such as different conventions to express time, speed, temperature, length, and so on. Also keep in mind that not every reader or translator is necessarily network literate.
Guidelines follow on how to write for the international market to enhance comprehensiveness, ease of translation, and consistency across documents.
Visually structuring a document by using clearly defined headings and text, illustrations, tables, bulleted lists, and numbered steps helps to organize and clarify information. When information is presented in a clearly defined format and broken into chunks, it is easy for an international audience to read and understand. The process of localization is also simplified.
In text use few words, and write brief paragraphs when possible. A lengthy, dense paragraph in English can cause a non-native speaker to feel discouraged. Breaking up long or complex paragraphs into visually more palatable chunks helps make the information easily accessible.
When writing for an international audience, be clear in structure and wording. Ambiguities in grammar or terminology cause misunderstanding and frustration for all readers and for international readers in particular.
The English language allows grammatical constructions and word creations that cannot—without cumbersome attempts to approximate the intended meaning—be mirrored in foreign languages. Therefore, clarity in writing for an international audience not only requires strict adherence to the rules of the English language, but also places additional demands on the writer. Examples of common linguistic ambiguities are described in the following sections.
Ambiguous Modifier Strings
Modifier strings are phrases with two or more nouns or adjectives strung together. In such strings, sometimes it is difficult to determine which word is modified by which adjective and which nouns form a standalone phrase.
New Cisco virtual private dialup network session counting software...
A translator could interpret this sentence in at least two ways:
New Cisco virtual private dialup counting software for network sessions...
New Cisco software for a new virtual private dialup network session counting...
A possible solution follows:
New Cisco software for counting sessions of virtual private dialup networks...
Avoid ambiguous modifier strings by breaking them into several smaller phrases, limiting the number of adjectives to no more than three, or adding hyphens to clarify compound adjectives.
Words with Multiple Meanings
Many words have multiple meanings. Eliminate ambiguities whenever possible.
Words that can be used as different parts of speech can be misinterpreted. Try to keep the use of such words, at least within the same paragraph, to one part of speech only.
Gerunds (verb forms ending in "-ing" that are used as nouns) and participles (verb forms ending in "-ing" that are used as adjectives) are often difficult to distinguish.
Searching the database.
This phrase could mean either "How to search the database" or "Database search is in progress."
When using gerunds and participles, make sure that your meaning is clear.
The conjunctions and and or can create ambiguities when it is unclear which text elements are being joined by the conjunction.
INCORRECT No translation is attempted between frame header bits and ATM layer EFCI bits and DE bits.
CORRECT No translation is attempted between the bits of the frame header and the EFCI and DE bits in the ATM layer.
To avoid confusion, use parallel construction and break up long or very complex sentences into simple sentences.
Abbreviations, Acronyms, Initialisms, and Blend Words
An abbreviation, acronym, initialism, or blend word is often jargon or a term used only in a restricted language community.
•An abbreviation is a shortened version of a word or phrase that replaces the word or phrase (for example: ft [feet]).
•An acronym is a word that is formed from the initial letters of a compound term (for example: RAM for random-access memory). Acronyms do not travel well across language boundaries, especially when the words or phrases that they represent occur in a different sequence in the other language.
•An initialism is an abbreviation that is formed by combining the initial letter of each word in a multiword term, with each letter being pronounced separately (for example: PPP for Point-to-Point Protocol).
•A blend word is a word that is made from parts of the words it represents (for example: TELEX).
Avoid any abbreviations, acronyms, initialisms, or blend words that are not standard usage within a well-established technical community. For example, RAM (random-access memory) is generally accepted, but NFAS (nonfacility-associated signaling) is not standard. Use your best judgment. When in doubt, spell out the word or phrase at first mention in the text.
An invisible plural can occur when a noun is used as an adjective in such a way that the reader has difficulty telling whether the noun or nouns being modified are singular or plural.
EXAMPLE ...the switch and router settings.
This phrase could mean "the settings for one switch and one router," "the settings for many switches and many routers," or "the on/off switch and the router settings."
The adjectives in this example are not inflected and do not show whether the noun is plural or singular. If you think that there is any possibility of confusion, rewrite the sentence.
EXAMPLE ...the settings for switches and routers.
Precise punctuation is essential for translators and the international audience to correctly parse a sentence. In fact, what might be considered overpunctuation is encouraged to help clarify the structure of a phrase or a sentence. The use of hyphens is especially recommended to eliminate the problems of ambiguous modifier strings. See the "Ambiguous Modifier Strings" section.
Sentences that are too long are not only stylistically cumbersome, but also can cause problems for the international reader. Long sentences are difficult to follow, which makes them apt to be misinterpreted.
EXAMPLE Each Fast Ethernet port can be configured for half- and full-duplex operation and includes a Media Independent Interface (MII) that can be used in back-to-back MII applications or with external, customer-supplied transceivers for connection to 100BASET-4.
The simplest way of fixing an overly long sentence is to break it up into small ones.
EXAMPLE Each Fast Ethernet port can be configured for half- and full-duplex operation. The port includes a Media Independent Interface (MII) that can be used in back-to-back MII applications or with external, customer-supplied transceivers. Fast Ethernet ports support connection to 100BASET-4.
In some cases, breaking up a long, complex sentence into a bulleted list is the best solution.
EXAMPLE With the support of FUNI, Frame Relay-to-ATM network internetworking, and Frame Relay-to-ATM service internetworking, you can make virtual connections between the following endpoints:
•Frame Relay and FUNI
•Frame Relay and ATM cell-based
•FUNI and ATM cell-based
A dangling modifier is a word, phrase, or clause that does not clearly modify an element in a sentence.
INCORRECT Also provided through web links, customers can perform basic troubleshooting operations, such as verifying software versions.
(It is not the customers who are provided through web links, but the troubleshooting operations.)
CORRECT Customers can perform basic troubleshooting operations, such as verifying software versions, which Cisco provides through web links.
To test whether a phrase is a dangling modifier, turn the phrase into a clause with a subject and a verb. If the expanded phrase and the independent clause do not have the same subject, the phrase is dangling.
Omitting the Pronoun "That"
Sometimes the relative pronoun that is dropped from sentences. In speech this omission is almost idiomatic, but in writing it can create problems for readers who are less familiar with English idioms. Do not omit that, especially in a sentence with a past-participle or present-participle construction.
INCORRECT AccessPath Manager is a web-based access management system designed to deploy and manage complex, distributed dial pools.
CORRECT AccessPath Manager is a web-based access management system that is designed to deploy and manage complex, distributed dial pools.
Telegraphic Writing Style
Telegraphic writing is a highly abbreviated, terse way of writing. Characteristically, this style omits the articles a, an, and the, and the words is, are, of, this, and these. Avoid writing in a telegraphic style because reading such text requires expertise in both the technical subject and English. Telegraphic sentences also lend themselves to mistranslation.
INCORRECT No translation attempted between frame header bits and ATM layer EFCI bits and DE bits.
CORRECT No translation is attempted between the bits of the frame header and the EFCI and DE bits in the ATM layer.
Units of Measure and Time Notation