Open Source Documentation Style Quick Start
Novell sponsors several open source projects such as Kablink Vibe, iFolder, and Identity Manager Scripting. See the Novell Developer website for information about other open source projects. As with any project, documentation is essential to help users understand how to use the product effectively and securely. Our goal is to help open source projects develop and provide quality documentation to the communities that the project serves.
We invite the project community members to contribute to the documentation development for the products they create. You can use the tips in this Style Quick Start to help your volunteer documentation contributions blend smoothly into the manuals prepared for Novell-sponsored open source projects.
Consistency in documentation organization, language, and format helps to convey information clearly and professionally and to enhance understanding of the software it describes. To encourage consistency, Novell maintains a Novell Documentation Style Guide as its primary source for information about writing documentation for Novell products. This Style Quick Start discusses some best practices from the Novell Documentation Style Guide, with special emphasis on areas that might differ from other software documentation.
For style information that is not addressed here, refer to The Chicago Manual of Style, 15th edition. For preferred spellings, refer to Merriam Webster’s Collegiate Dictionary, 11th edition.
1.0 Style, Grammar, and Usage
Novell follows the basic style, grammar, and usage rules found in The Chicago Manual of Style. This section lists exceptions to and variations of those rules, although a few rules from Chicago are reiterated here.
1.1 Case-Sensitivity
Case-sensitive software distinguishes between uppercase and lowercase. Case sensitivity might apply for command syntax, user names, passwords, URLs, and names of files, directories, volumes, and servers.
Document case-sensitive software carefully. When a command is entered in the wrong case in case-sensitive software, the command fails.
1.2 Commas in a Series
Use a comma to separate all items in a series of three or more items. For example:
- Provide the name of the remote host, your file name, and your password.
1.3 Headings
-
Use the gerund form of verbs in task headings. For example, use “Setting Up a Server” instead of “To Set Up a Server” or “Server Setup.”
-
Use nouns or short noun phrases in headings for conceptual or reference-oriented sections. For example, use “Overview of iFolder” and “Glossary.”
1.4 Gender-Neutral Language
-
In general, use the second person (“you”) in documentation. Speaking directly to the user avoids the need for a third-person pronoun (which, in English, requires gender).
-
When it is impossible to use the word “you,” try to structure the sentence to avoid using a third-person pronoun. For example, use one of the following proper methods of avoiding sexist language:
-
Make the subject plural and use plural pronouns such as “they” or “their.”
-
Use job titles, not pronouns.
-
Use a definite article (the) or an indefinite article (a, an) instead of a possessive pronoun (his or her).
-
-
If you must use a third-person pronoun, use the phrase “he or she” when referring to a single individual (and “his or her” as possessive pronouns).
-
Do not use the following improper methods of avoiding sexist language:
-
Adding a disclaimer regarding sexist language in the introduction to the documentation
-
Using “they” or “their” with a singular antecedent
-
Using “he” or “she” in alternating paragraphs or on alternating pages
-
Using “s/he” or “(s)he”
-
Using “he/she” or “she/he”
-
1.5 Naming Conventions
Protect proprietary or private information. Do not use the real names (first and last), or the phone numbers, extensions, mailstops, passwords, TCP/IP addresses, URLs, user IDs, or email addresses of actual employees or others in your screen shots, scripts, contexts, trees, or other examples. Likewise, do not use real workstation, server, directory, or directory tree names. Doing so creates a high security risk.
Avoid using names of fictional characters and public figures such as politicians, authors, musicians, and actors.
Modify any proprietary or private information that is displayed on the screen before capturing a screen shot, whenever possible. You can also edit the graphic afterwards to replace this type of information with generic information. For example:
-
Replace operational IP addresses with reserved private IP addresses such 192.168.1.1 to 192.168.1.255 or 10.0.0.0 to 10.255.255.255.
-
Replace operational domain names with example.com, which is a domain name that is reserved for use in documentation.
-
Replace real file names with generic names from regions around the world.
1.6 Path Names, File Names, and Directory Names
If your documentation applies to Linux, Mac, or UNIX, use the forward slash (/) in path names. Because Linux is case-sensitive, present path names, file names, and directory names exactly as the operating system recognizes them. For example, /mnt/user/Provo/Webac65a/page.html.
If your documentation applies to Windows or case-insensitive operating environments, use a backslash (\) in path names, such as C:\Provo\Webac65a\page.html. Honor capitalization only if it is important to do so for any of the supported platforms; otherwise, use lowercase for path names, such as c:\provo\webac65a\page.html.
1.7 Quotation Marks
If your authoring tool uses “smart quotes” (curly quotation marks), be sure to use straight quotes in code samples and syntax examples, especially if the sample might be copied for programming or in command line commands.
1.8 Verb Tense
-
In general, use active voice instead of passive.
-
Active voice is usually more concise and more forceful than passive voice, and it emphasizes the doer of the action. For example:
- Weak passive: The network must be updated by the administrator.
- Strong active: The administrator must update the network.
-
Use passive voice to change emphasis to the receiver of the action rather than the doer. For example:
- Files are processed immediately.
-
Use passive voice when the agent is either not known or not important. For example:
- Output is sent to the nearest printer.
-
-
Use the simple present tense almost exclusively. Unless there is a very clear shift in time from past to present or a very clear reference to the future, describe a series of actions in the present tense. For example:
- Incorrect: The password contained an invalid character.
- Correct: The password contains an invalid character.
-
State perpetual cause-and-effect relationships (every time x happens, y occurs) in the present tense. For example:
- Incorrect: When you select this command, GroupWise will open the text files.
- Correct: When you select this command, GroupWise opens the text files.
-
Use future tense only when anticipating an event that is yet to happen. For example:
- In the next lesson, you will learn how to write a macro.
2.0 Trademarking
Do not include trademark symbols in the body of manuals or help. Trademarking is addressed in the front matter and legal notices sections that are added for publication.
3.0 Common Usage
|
Use |
Don’t Use |
Example |
|---|---|---|
|
and or |
and/or Whenever possible, use just “and” or “or.” |
Click or to save your changes. |
|
appendixes |
appendices |
|
|
can, might |
may Reserve “may” for use in cases where permission is sought or given, such as in a legal statement. |
The CD might contain multiple languages. |
|
check box Avoid using where possible and just use the option name. |
checkbox |
In the dialog box that appears, select . Select the check box at the top of the column to select all jobs. |
|
click Use “click” when a user performs an action on items that were previously selected. (See also select.) |
click on |
Click to save your changes. |
|
computer For increased clarity, use the terms “workstation,” “server,” or “mainframe” whenever possible. Use “device” for mobile devices. |
Don’t use “machine” or “system” for generic references. |
|
|
device |
Don’t refer to mobile devices as smartphones, pagers, iPads, tablets, and so on unless the solution is specific to a device type or brand. |
|
|
dialog box |
dialog However, in the Linux interface, “dialog” is used to describe some user entry areas, such as the YaST installation workflow, where the sequential dialogs are full screen, without a frame. |
|
|
dimmed, unavailable |
grayed, grayed out |
|
|
drop-down Hyphenated when used as an adjective, two words when used as a verb. Never used as a noun. |
dropdown |
In the drop-down list, select . |
|
|
|
|
|
end user Just write “user” unless it’s necessary to distinguish between the “end user” and another kind of “user.” |
enduser, end-user |
|
|
enter Use the verb “enter” only when you want users to type something and press the Enter key. If users are simply adding text to a field, use “type,” “specify,” or “provide.” |
At the server console, enter grpwise.ncf to load the agents. Specify the name of the directory tree. |
|
|
Enter Use when referring to the key on the keyboard. |
Return |
Press Enter. |
|
etc. This is the only Latin abbreviation you should use. |
e.g., i.e. Use “such as” or “for example” instead. |
|
|
field, list, drop-down list, option Using generic terms avoids overloading the user with specialized terminology. (See also interface terminology.) |
combo box, spin box, combination box, drop-down combination box, text box, group box. |
Fill in the fields. Select your server name from the list of available servers. Select the options you want. |
|
file name |
filename You can use the one-word spelling in syntax or code examples. |
|
|
hard copy, hard-copy. Two words for the noun, hyphenated for the adjective. |
hardcopy |
|
|
host name (in Windows) hostname (in Linux, Mac, and UNIX) |
||
|
interface terminology When possible, use the name of the option without adding “box,” “field,” “option,” “button,” etc. However, do use specific locators when it’s necessary for clarity. |
Click . Select . If necessary for clarity: Click the button. Select the option. |
|
|
Key names:
|
Don’t use special formatting, all caps, or icons. In general, use the key name only; don’t add the word “key” unless it’s necessary for clarity. |
Press Enter. Press Tab. Press the Plus key. |
|
man page |
manpage |
|
|
menu |
shortcut menu pop-up menu |
Right-click to display a menu of options. Right-click, then select Paste from the menu that appears. |
|
menu bar Seldom used. |
menubar |
|
|
might, can |
may Reserve “may” for use in cases where permission is sought or given, such as in a legal statement. |
You might need to set additional options before proceeding. |
|
open source |
open-source Open Source (unless it’s a reference to the OSI trademark.) |
open source software The idea behind open source is that the code is available. |
|
option button Avoid using where possible and just use the option name. |
radio button |
If you want to continue numbering from the previous file, select . |
|
path name |
pathname You can use the one-word spelling in syntax or code examples. |
|
|
plug-in (noun, adjective) plug in (verb) Use “plug-in” to describe files or tools that alter, enhance, or extend the operation of a parent application that uses a standard Web browser to display the interface. (See also snap-in.) |
plugin |
Use the iManager plug-ins to manage your application. |
|
pop-up (noun, adjective) Seldom used. (See also menu.) |
popup |
|
|
press Use “press” to refer to the keys on the keyboard. (See also Key names.) |
hit, punch |
Press the Spacebar. Press Ctrl+Alt+Del once to bring up the Task List. |
|
scroll bar, scroll box |
scrollbar, scrollbox |
|
|
select Use “select” to tell a user to identify an item prior to carrying out an action on the item. Use “deselect” as the opposite of “select.” |
choose, highlight, block. |
Select the options you want, then click to add them to the list. Deselect the options for continued numbering. |
|
snap-in (noun, adjective) snap in (verb) Use “snap-in” to describe files or tools that alter, enhance, or extend the operation of a parent application that provides its own GUI to display the interface. (See also plug-in.) |
snapin |
The installation process adds the ConsoleOne® snap-ins. |
|
standalone (noun, adjective) |
stand-alone |
|
|
start and restart (Windows) boot and reboot (Linux) |
|
|
|
status bar |
statusbar |
|
|
step separator Use > when you’re telling a user to click a series of menu items or tabs. Use commas when you’re telling a user to perform a series of actions within a dialog box or property page. |
The pipe symbol (|) or an icon. |
Click . Select the text, select the font, then click . |
|
submenu |
sub-menu |
|
|
time stamp |
timestamp |
|
|
title bar |
titlebar |
|
|
type Use “type” when you want users to type something without pressing the Enter key. When possible, use a more generic verb such as “specify” or “provide.” |
enter |
Type the name of the server. Specify the path name. |
|
user name |
username You can use the one-word spelling in syntax or code examples. |
|
|
web page, website, web server |
webpage, web site, webserver |
|
|
webmaster |
Webmaster |
|
4.0 Legal Notices:
Copyright © 2013 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher. For Novell trademarks, see the Novell Trademark and Service Mark list. All third-party trademarks are the property of their respective owners.