Editorial Cheat Sheet for OpenSolaris Documentation

Use these guidelines to bring consistency in editorial style to OpenSolaris documentation.

Readers project some significance onto every change in language, tone, or typographic convention. A consistent style enables readers to internalize the language and text conventions of the document. As a result, understanding occurs more easily and significant points stand out more clearly. Consistency is one of the most valuable aspects of good style. In addition, consistency improves clarity for translation purposes.

The following sections are provided:

• GUI Tips
• Headings
• List Construction Guidelines
• Procedure Writing Tips
• Pronoun Usage Guidelines
• Punctuation Guidelines
• Referencing Man Pages
• Referencing URLs
• Referring to Sun's Trademarked Terms
• Terminology Guidelines

GUI Tips

When writing about graphical user interfaces (GUIs), follow these guidelines:

• Show field names and menu option names as they appear in the GUI. However, you may add initial capital letters even if the words are not capitalized in the interface only to increase the readability of running text.

Incorrect: Select Prompt for credentials for every server for maximum security.

Correct: Select Prompt for Credentials for Every Server for Maximum Security.

• Do not use special text formatting such as an alternative font or bold type for GUI element names such as menu names, menu options, or field names. In addition, do not enclose GUI element names in quotation marks.

• Do not include a colon or ellipsis points associated with the field name or menu option when mentioning the item in running text.

• When writing about GUIs, reserve certain terms for specific activities. The following table lists common usages. The terminology of your GUI might require alternatives.

Table 1 GUI Terms

Headings

• Capitalize the first letter of the first word of a title or heading, and the first letter of all other words in the title or heading except conjunctions, articles, prepositions of fewer than four letters, and the “to” in infinitives.

What Is the OpenSolaris Project?

Getting Started With Solaris Dynamic Tracing

How to Install the OpenSolaris 2008.05 Release

How to Boot a System From the Network

Structural Differences Between Kernel Modules and User Programs

Write Procedures That Are Easy to Follow

• Avoid ambiguous one-word headings such as “Overview.” Such headings are meaningless when viewed out of context, as in the search results list. Add more context to make headings meaningful.

Incorrect: Overview

Correct: Solaris Kernel Overview

• Keep headings short but as meaningful as possible. Concise headings are easier to scan in text and in the table of contents.

Incorrect: Roadmap for OpenSolaris Feature Documentation

Correct: OpenSolaris Documentation Roadmap

• Place the most important words first.

Incorrect: Features of the OpenSolaris Project

Correct: OpenSolaris Features

• Avoid starting headings with an article.

List Construction Guidelines

Lists are used to break out information from the paragraph format and to structure the information into an easier-to-read format. Lists must include at least two items. If a list has more than nine items, try to identify a way to divide the list into two or more lists. Follow these guidelines when constructing lists:

• Use unnumbered (bulleted) lists when the items are not dependent on the sequence in which you present them. When the items are dependent on sequence, use numbered lists with numerals and letters to build the hierarchy.
• Use running text when you have up to four one-word items that have equal weight and no order. Incorporate the items in a sentence in which the items are separated with serial commas. Otherwise, use a vertical list.

  In the following example, a two-item list is embedded in running text.

Incorrect:

Two commands indicate when instructions are executed. The sed instructions that follow the !install command are executed during package installation. The sed instructions that follow the !remove command are executed during package removal. The order in which these commands are used in the file does not matter.

Correct:

The following commands indicate when the sed instructions are executed:

• !install command – Indicates that the instructions are executed during package installation
• !remove command – Indicates that the instructions are executed during package removal

The order in which these commands are used in the file does not matter.

• When introducing a list, use a colon if the introduction clearly anticipates the list, especially if the introduction contains phrasing such as “the following” or “as follows.” If the introduction is complete in itself, use a period. For example, you could use either of these statements to introduce the same list:

  Send a mail message in any of the following three ways:

  The system provides three convenient ways to send a mail message.

• When you use a complete sentence or a phrase with a colon to introduce an unnumbered list, be sure that the syntax of the items in the list is parallel and agrees with the syntax of the introduction.

Incorrect:

You can use Mail Tool to perform the following tasks:

• Compose a new message
• Replied to a message sent to you
• Forwarding a message to another person

Correct:

You can use Mail Tool to perform the following tasks:

• Compose a new message.
• Reply to a message that was sent to you.
• Forward a message to another person.
• For consistency in capitalization and punctuation, follow these guidelines when you construct the items in lists:
  • Capitalize the first word of each list item in all lists, except for placeholders and other literal computer terms.
  • Use punctuation at the end of each item in a list of complete sentences.
  • Use no punctuation at the end of each item in a list of sentence fragments.
  • Avoid mixing complete sentences and sentence fragments in the same list. If you must have a mixed list, add periods at the end of every list item.

Procedure Writing Tips

The purpose of many technical documents is to explain how to use a product to accomplish specific tasks. In such documents, detailed instructions on how to accomplish tasks are often provided in the form of procedures. Procedures contain an ordered set of steps.

To write effective procedures for your audience and the task at hand, follow these general guidelines:

• Make sure that you establish the entire context in which the procedure is done.
• Include any prerequisite information, either in introductory material or as the first step.
• Try to limit the number of steps.
• Provide explanatory text and visual cues.

  Tell readers what is to happen after each step. For example, if a window opens as a result of a step, state that the window opens, and refer to the window by its name.

• Include all required procedural information.

  However, do not provide a detailed description of each window, menu, or field in an interface. Similarly, do not put overview information in the procedure.

When writing steps, determine what a user needs to do first, next, and last. Write clearly so that a user understands exactly what to do. To write clear, concise steps, follow these guidelines:

• Order and number the steps. If users must perform different actions based on the outcome of a step, use a bulleted list to show the alternatives. Use letters for substeps.

  In the following example, note the use of step alternatives, branching, and substeps.

1. Determine whether you need to remove the disk drive.
   • If no, go to Step 2.
   • If yes:
     1. Gently pull back on foam piece 2.
     2. Slide the disk drive out of foam piece 2.
     3. Place the drive on the antistatic mat.
2. Carefully lift the component from the unit.

• Use bold for the step text and any command-line syntax, if possible with your writing tool. In addition, use monospace font for command names and options, file names, IP addresses, and system variables. Use italic for variables and command-line placeholders.

4. To examine a crash dump, use the mdb utility.

     # /usr/bin/mdb -k crashdump-file

   where crashdump-file is the name of the crash dump file for the operating system. The -k option specifies kernel debugging mode.

• Make each step short and equivalent to one action.
  • Do not bury steps in a paragraph.
  • Try to use no more than 20 words to write each step.
  • Write about only one action in each step.

  You can include a short phrase that does not need to be its own step. For example, you can include “and press Return” or “and click OK” at the end of the step.

  • Make sure that you include steps for all actions that the user must perform.

• Place any explanatory text in a separate paragraph under the step text, and keep the explanatory text as short as possible.

Incorrect:

1. Choose File → Find.
2. After you make this selection, the Find dialog box appears.
3. In the Find field, type the text that you want to locate. Because this search is case-sensitive, be sure to use appropriate capitalization.

Correct:

1. Choose File → Find.

   The Find dialog box appears.

2. In the Find field, type the text that you want to locate.

   This search is case-sensitive.

• Write each step as a complete, correctly punctuated sentence in the imperative mood.
• Do not use command names as verbs.

Incorrect:

3. cd to the new directory.

Correct:

3. To change to the new directory, type cd directory-name.

• Write meaningful steps.
  • For GUI procedures, state what data the user needs to type in a text field, which menu option the user must choose, and so on. For example:

  Incorrect:

  4. Send the message to the recipients.

  Correct:

  4. Click Send.

     The message is sent to the recipients.

  Note that in GUI procedures, the task (“Send the message...”) is not the focus of the step, as is the case with command-line procedures.

  • For command-line procedures, make the task, not the command, the focus of the step. Follow the step immediately with command syntax, if applicable.

  Incorrect:

  3. Type ufsrestore and press Return.

  Correct:

  3. Verify that you successfully backed up the system.

       # ufsrestore -t

  Follow the step and the command line with a description of the command options and variables, or with a man page reference, as necessary.

• Indicate optional steps by including the word “Optional” in parentheses.

3. (Optional) Reboot the system.

• Explain to readers why they are to skip a step or jump to a step.

5. Determine whether you want the partition table to be the current table.

   • If you want to change the displayed partition table, type n and go to Step 8.
   • If you want to use the current partition table, type y when prompted:

     Okay to make this the current partition table [yes] y

• Use branching of steps appropriately.
  • Use branching if the action to take at a particular step in a procedure differs depending on the user's situation or desired outcome.
  • Use branching if the procedure is the same for many cases and differs only at one or two steps.

2. Format the diskette.

   • To format the diskette for a UFS file system, type fdformat and press Return.
   • To format the diskette for an MS-DOS file system, type fdformat -d and press Return.

• Do not use branching for substeps. Use a., b., c. for substeps.

Pronoun Usage Guidelines

Follow these guidelines when using pronouns:

• Except for blog entries, do not use first-person pronouns in OpenSolaris documentation.

Incorrect: We recommend that you install the custom components only on large systems.

Correct: Install the custom components only on large systems.

Incorrect: We can write a protocol specification that describes the remote version of printmessage().

Correct: You can write a protocol specification that describes the remote version of printmessage().

Incorrect: Let's assume that the user already has an account on the system.

Correct: Assume that the user already has an account on the system.

• Avoid the indefinite pronoun or indefinite possessive pronoun, especially at the beginning of a sentence, unless the noun to which the pronoun or possessive pronoun refers is clear.

  A pronoun that forces a reader to search for an antecedent can frustrate or mislead the reader. Pronouns that typically cause this type of confusion include “it,” “they,” “its,” “theirs,” “this,” “these,” “that,” and “those.”

Incorrect: It also describes how to install the OpenSolaris OS.

Correct: This chapter also describes how to install the OpenSolaris OS.

Incorrect: You can use these either individually or together.

Correct: You can use these two options either individually or together.

Incorrect: The value in this variable is used to determine when to pause during long display output, such as during a software dump. Its value is reset each time the ok prompt is displayed.

Correct: The value in this variable is used to determine when to pause during long display output, such as during a software dump. The variable's value is reset each time the ok prompt is displayed.

• Remember to use “its” as the possessive form of “it,” not “it's,” which is a contraction for “it is.”

Incorrect: This site describes the application and it's accompanying utilities.

Correct: This site describes the application and its accompanying utilities.

Punctuation Guidelines

Apply the following punctuation guidelines:

• Use commas to separate the items in a series of three or more words, phrases, or clauses. Use the comma serial style. In other words, use a comma before the conjunction that joins the last two items in a series.

Among your hidden files are .cshrc, .defaults, .login, and .mailrc.

• Avoid using an em dash for explanatory or appositive purposes. Using an em dash can hinder clear writing by causing the reader to pause. The use of em dashes can also result in sentences that are difficult for readers to understand because the sentences contain more than one main idea. Break a sentence in which em dashes are used for explanatory purposes into two sentences.

Incorrect: After a context is established between two peers—say, a client and a server—messages can be protected before being sent.

Correct: After a context is established between two peers, messages can be protected before being sent. An example of two peers is a client and a server.

In sentences that use em dashes for appositive purposes, replace the em dashes with commas.

Incorrect: This book—an API guide for developers—is referred to often.

Correct: This book, an API guide for developers, is referred to often.

• Avoid using semicolons. Semicolons are often misused and are difficult to read online. For conjoined sentences, consider rewriting the text as separate sentences.

Incorrect: The redirects contain the link-layer address of the new first hop; separate address resolution is not necessary.

Correct: The redirects contain the link-layer address of the new first hop. Separate address resolution is not necessary.

Referencing Man Pages

UNIX commands are documented in reference materials known as man pages or reference manual pages. When referring to man pages in text, follow these guidelines:

• Include the reference manual section number next to the first reference of a command or function name only when you think the reader might benefit from reviewing the man page in relation to the information in the text.
• The first time you include a command in a procedure, cross-reference the command's man page in the explanatory text following the step. If the command appears later in the same procedure or section, cross-reference the man page again only if doing so in that context helps readers.
• Do not include the reference manual section number next to the command or function name in the following situations:
  • In every mention of the command or function if it is referenced numerous times in a paragraph or series of paragraphs
  • In titles or section headings
  • In table, figure, or example captions
• Use monospace font for the command or function name, and regular text font for the reference manual section number, which should appear in parentheses. Capitalize the letter in a man page section, for example, 1M.
• Make sure that instructions to the reader about how to access the man page are clear. This guideline makes the man page reference clearer to the reader and benefits translation as well.

Incorrect: See ioctl(2).

Correct: See the ioctl(2) man page.

The “man” part of the term “man page” when used generically is treated as a standard English word and capitalized in headings and at the beginning of a sentence. For example, “Man pages are very helpful.” However, the man command appears in monospace font and is always lowercase, as is the case for all command names.

Referencing URLs

Use monospace font for URLs. When introducing URLs, follow these guidelines:

• Make references to URLs as simple and direct as possible.

  Readers no longer need to be told to type a URL. For example, you do not need to write detailed instructions such as “Point your browser at the following URL.”

Incorrect: You can find further information by typing the following URL: http://opensolaris.org.

Correct: Further information is available at http://opensolaris.org.

Incorrect: Open the following URL in your browser: http://opensolaris.org.

Correct: Go to http://opensolaris.org.

• Precede a URL with “at” or “to” when a preposition is needed.

Incorrect: Check for updates on http://opensolaris.org.

Correct: Check for updates at http://opensolaris.org.

Correct: To check for updates, go to http://opensolaris.org.

• Provide explanatory text about the web site before giving the URL. A URL is acceptable at the end of a sentence. Readers no longer confuse end punctuation with spelled-out URLs.

Incorrect: Go to http://opensolaris.org for resources for users and developers.

Correct: For resources for users and developers, go to http://opensolaris.org.

• When placing URLs in text, follow these guidelines:
  • If the URL is long, place the URL on its own line, introduce it with a colon, and do not put a period at the end.
  • If the URL is extremely long, provide the base URL and an indication of which links to click to get to the specific page.
  • If the URL is short, weave it into the sentence.
  • If your document provides two or more URLs in the same paragraph, place them in a bulleted list.

Referring to Sun's Trademarked Terms

The scope and strength of a company's exclusive rights in its trademarks are weakened when the trademarks are not used properly. This precept applies even when the trademarks are registered. A number of well-known names, such as “escalator,” “aspirin,” and “cellophane,” were once trademarks. Because these names have fallen into common usage, the terms are now generic and can be used by anyone.

Follow these guidelines to protect Sun's trademarks, especially its core Solaris and Java trademarks:

• To determine whether a term is trademarked by Sun, go to http://www.sun.com/suntrademarks/. This web page contains a list of Sun's trademarked terms.
• If a term is trademarked, be sure to use the trademarked term as an adjective, not as a noun or verb.

Incorrect: JavaBeans is fun and easy to use.

Correct: JavaBeans components are fun and easy to use.

Incorrect: Javatize the system.

Correct: Enhance the system for the Java platform.

• Do not abbreviate trademarks. For example, do not write “SMC” for Sun Management Center because “Sun” is a trademarked term.

Terminology Guidelines

Abbreviations and Acronyms

When using abbreviations or acronyms, follow these guidelines:

• In most cases, expand the term and enclose its abbreviation or acronym in parentheses the first time the term is used in text. Then, continue using the abbreviation or acronym alone.

A local area network (LAN) consists of computer systems that can communicate with one another through connecting hardware and software. Your company probably uses a LAN.

• In books, repeat the spelled-out version at least at the first occurrence in each chapter where the abbreviation or acronym appears.

  In online help and other topic-based online documents, repeat the spelled-out version at the first occurrence in each topic. In this context, a topic is typically self-contained and resides in its own file.

• If you are certain that an abbreviation or acronym is a standard term for your target audience, you do not need to spell it out at any occurrence.

  For example, you do not need to spell out “CD-ROM,” “RAM,” or “CPU” in a system administration book. However, if you are uncertain, err on the side of caution, and spell out the abbreviation or acronym.

• When writing out the full word or phrase, do not capitalize any letters unless the letters are capitalized as part of a standard or begin a proper noun.

floating-point unit (FPU)

Internet Protocol (IP)

• Avoid first usage of an abbreviation or acronym in a chapter title, heading, or caption.

  If using an abbreviation or acronym for the first time in a chapter title, heading, or caption is unavoidable, do not enclose the abbreviation or acronym in parentheses next to the full word or phrase. Use either the full word or phrase or the abbreviation or acronym, depending on which item is more familiar to your audience. Then, provide the explanatory text or the abbreviation or acronym in the paragraph immediately following the chapter title, heading, or caption.

Common Term Usage and Style

This section lists and briefly explains how to correctly use terms that are frequently used in OpenSolaris documentation.

• boot (Use instead of “boot up” or “bootup.”)
• command line (noun), command-line (modifier)
• command-line interface (CLI)
• file name (noun, modifier), filename (variable) (Note two words without hyphenation when used as a noun or modifier.)
• file system (Note two words without hyphenation when used as a noun or modifier.)
• host name (noun), host-name (modifier), hostname (variable)
• install (verb)
• installation (noun, modifier)
• log in to (verb) (Use instead of “log into.”)
• OpenSolaris (Note that “OpenSolaris” is a trademarked term, so it should be followed by a noun such as "project," "source code," or "operating system.")
• open source (noun, modifier)
• path name (noun), path-name (modifier), pathname (variable)
• recommend (Do not use. Just go ahead and recommend. For example, “Back up all your files once a week.”)
• shutdown (noun, modifier), shut down (verb)
• Solaris Operating System (Solaris OS) (At first reference, use spelled-out form with the abbreviation in parentheses. Then, use the abbreviation.)
• UNIX (Note capitalization.)
• user name (Note two words.)