Guest

Support

Chapter 2: Appropriate Use of Language

  • Viewing Options

  • PDF (411.8 KB)
  • Feedback
Appropriate Use of Language

Table Of Contents

Appropriate Use of Language

Accessibility Features

Bias-Free Documentation Policy

Cisco IOS Software Release Naming Convention

Company Names, Product Names, and Trademarks

Domain Names and IP Addresses in Documentation

Domain Names

IP Addresses Reserved for Documentation

IP Addresses Reserved by Cisco

Private IP Addresses

IP Multicast Addresses

The Loopback (or Localhost) Address

The IPv6 Reserved Prefix

Gender-Neutral Language

Human Characteristics Attributed to Technology

Jargon and Slang

Names and Passwords

Past, Present, and Future Tense

Project Code Names

URL References

Voice

Website References

Writing for an International Audience

Document Organization

Clear Writing

Ambiguous Modifier Strings

Words with Multiple Meanings

Ambiguous Conjunctions

Abbreviations, Acronyms, Initialisms, and Blend Words

Invisible Plurals

Precise Punctuation

Long Sentences

Dangling Modifiers

Omitting the Pronoun "That"

Telegraphic Writing Style

Units of Measure and Time Notation

Additional Guidelines


Appropriate Use of Language


This chapter provides guidelines for using appropriate language in Cisco documentation.

This chapter contains the following sections:

Accessibility Features

Bias-Free Documentation Policy

Cisco IOS Software Release Naming Convention

Company Names, Product Names, and Trademarks

Domain Names and IP Addresses in Documentation

Gender-Neutral Language

Human Characteristics Attributed to Technology

Jargon and Slang

Past, Present, and Future Tense

Project Code Names

Voice

Website References

Writing for an International Audience

Accessibility Features

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:

Domain Names

IP Addresses Reserved for Documentation

IP Addresses Reserved by Cisco

Private IP Addresses

IP Multicast Addresses

The Loopback (or Localhost) Address

The IPv6 Reserved Prefix


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.


Domain Names

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.

Address Block
Starting Address
Ending Address
Broadcast Address
Subnet Mask

209.165.200.224/27

209.165.200.225

209.165.200.254

209.165.200.255

255.255.255.224

209.165.201.0/27

209.165.201.1

209.165.201.30

209.165.201.31

255.255.255.224

209.165.202.128/27

209.165.202.129

209.165.202.158

209.165.202.159

255.255.255.224


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

10.0.0.0/8

10.0.0.0

10.255.255.255

16,000,000

172.16.0.0/12

172.16.0.0

172.31.255.255

1,000,000

192.168.0.0/16

192.168.0.0

192.168.255.255

65,000


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 224.0.0.0/8 to 239.0.0.0/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).

Network Prefix
Starting Address
Ending Address
Example Host

2001:DB8::/48

2001:DB8::1

2001:DB8:0:FFFF: ... :FFFE

2001:DB8:0:ABCD::1

2001:DB8::/64

2001:DB8::1

2001:DB8:0:0:FFFF: ... :FFFE

2001:DB8:0:0:E000::F

2001:DB8:0:1::/64

2001:DB8:0:1::1

2001:DB8:0:1:FFFF: ... :FFFE

2001:DB8:0:1:FFFF:1234::5


Gender-Neutral Language

Use the following guidelines to avoid sexist or gender-specific language:

Articles

Use articles instead of gender-specific pronouns.

CORRECT  The system administrator maintains the network for all users in the group.

INCORRECT  The system administrator maintains the network for all users in his group.

Masculine terms

Use gender-neutral or all-inclusive terms to refer to human beings, rather than using "man" and similar masculine terms.

For example, use Chair instead of Chairman; use sales representative instead of salesman; use operates or staffs instead of mans.

Plurals

Use the plural form and maintain parallel structure.

Pronouns

Do not use the following conventions: he/she, his/her, him/her.

Use the instead of his or rewrite the material in the second person (you) or in the plural.

Do not use gender-specific pronouns.

Second person

Use the second person.

CORRECT  Specify the transmission rate for the modem that you are using.

INCORRECT  The sender must specify the transmission rate for the modem.


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

Present tense

Use the present tense whenever possible. This tense is direct and active, and helps readers scan the material quickly.

EXAMPLE  Perform system management tasks to monitor and improve the router's performance.

Past and future tense

Use the past and future tenses only when it is confusing to use the present tense—for example, when it is essential to describe events in terms of the past or future, as when a future event will be caused by a present action.

EXAMPLE  If you want to use the macro in your network, you will want that macro to play back at the same speed at which it was recorded.


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.

INCORRECT  Humperdinck route processor

CORRECT  Cisco Performance Routing Engine 2 (PRE2) route processor

URL References

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.

Voice

Active voice

The active voice is usually more direct and vigorous than the passive. When you write a sentence in the active voice, it is also usually shorter than in the passive voice. Use the active voice whenever possible.

CORRECT  Fast EtherChannel establishes a high-bandwidth connection between two switch devices.

INCORRECT  A high-bandwidth connection between two switch devices is established by the use of Fast EtherChannel.

Passive voice

The passive voice looks at an action from the point of view of the target or recipient, not the actor or agent. The passive voice is most appropriate when the originator or performer of an action is unimportant, unknown, or hard to identify.

EXAMPLE  The document set was published on CDC.


Website References

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.

Document Organization

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.

Clear Writing

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.

EXAMPLE

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

or

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.

EXAMPLE

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.

Ambiguous Conjunctions

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.

Invisible Plurals

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

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.

Long Sentences

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

FUNI

Frame Relay and FUNI

Frame Relay and ATM cell-based

FUNI and ATM cell-based

Dangling Modifiers

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

Units of measure

Because many countries use the metric system, always give both the British measurement unit and the metric system measurement. The following units are the most common:

Length

1 mile (1.6 kilometers)

1 foot (0.3 meter)

1 inch (2.54 centimeters)

Weight

1 pound (0.45 kilogram)

Temperature

50° Fahrenheit (10° Celsius)

Time

Many countries use 24-hour notation to express time. Always express time by showing the U.S. time notation followed by the 24-hour notation in parentheses.

EXAMPLE  8:00 a.m. to 5:00 p.m. (0800 to 1700)

In the 24-hour notation system, no punctuation or abbreviations are used.

EXAMPLE  Breakfast was at 0645; our first meeting was at 0800.


Additional Guidelines

Government names

Do not generalize names of specific government agencies, institutions, or organizations.

Because many of our readers are in other countries, generalization can be misleading. If you are referring to a specific U.S. government agency, say so. Some of the terms to watch out for are federal, national, government, and Department of Defense.

CORRECT  This project was funded by the U.S. government.

INCORRECT  This project was funded by the federal government.

CORRECT  July 4 is a U.S. holiday.

INCORRECT  July 4 is a national holiday.

Graphics

Use figures, icons, and symbols that are universally recognizable. For example, do not use a dollar sign as an icon for a bank. What is considered appropriate in images and colors varies widely among cultures.

Names

Do not use names in examples. Use the title of the role instead (for example, administrator, technician, and so on).

National-centric phrases

Avoid the use of the word domestic to refer to the United States because it is U.S.-centric. For the same reason, do not use non-U.S. Instead, use terms such as within the United States, outside the United States, global, worldwide, and international.

Nouns and adjectives

Use U.S. and U.K. as adjectives; use United States and United Kingdom as nouns.

Safety warnings

The regulatory agencies of other countries require that translated safety warnings ship with Cisco products. These warnings are translated into multiple languages and must be included in your documentation set.

Note If you edit any safety warnings, they must be retranslated.

Seasons

Do not refer to seasons of the year to specify time because seasons vary around the world. If possible, refer to specific months. If you must refer to a period of time, refer to calendar quarters.

CORRECT  The new router will be available in the fourth quarter of 2000.

INCORRECT  The new router will be available in the winter of 2000.

Toll-free numbers

Use toll-free number, not 800 number, to refer to phone numbers that have no calling fee.