Product SiteDocumentation Site

Open-Source Style Guide

Manual for Technical Writers

Documenting software projects and products

Edition 0

Red Hat Engineering Content Services

Edited by

Rüdiger Landmann

Red Hat Engineering Content Services

Legal Notice

Copyright © 2010 Red Hat, Inc. and others
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution 3.0 Unported license ("CC-BY"). An explanation of CC-BY is available at http://creativecommons.org/licenses/by/3.0/. In accordance with CC-BY, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Abstract
A short overview and summary of the book's subject and purpose, traditionally no more than one paragraph long. Note: the abstract will appear in the front matter of your book and will also be placed in the description field of the book's RPM spec file.
Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. We Need Feedback!
1. Word Usage
Glossary
2. Punctuation
2.1. Colons and semicolons
2.1.1. To relate clauses
2.1.2. To introduce a series or list
2.2. Commas
2.2.1. In compound sentences
2.2.2. In adverbial clauses and phrases
2.2.3. In adjectival clauses and phrases
2.2.4. With coordinate adjectives
2.2.5. With series and lists
2.3. Parentheses
2.4. Quotation Marks
2.5. Apostrophes
3. Grammar
3.1. Active Voice
3.2. Agreement
3.2.1. Pronoun-Antecedent Agreement
3.3. Sentence Structure
3.3.1. Sentence Fragments
3.3.2. Run on sentences
3.4. Contractions
3.5. Gender References
3.6. Tense
4. Design
4.1. Heading Styles
4.2. Screenshots
4.3. Diagrams
4.4. Example Domain References
4.5. Example Computer Output
4.6. Admonitions
4.7. Additional Resources
4.8. Book References
5. Avoiding Slang
Glossary
6. Cross References
7. Standard Terminology
Glossary
8. XML Tags
9. Resources
Bibliography
A. Revision History
Index

Preface

1. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight keycaps and key combinations. For example:
To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold and all distinguishable thanks to context.
Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to the first virtual terminal. Press Ctrl+Alt+F1 to return to your X-Windows session.
The first paragraph highlights the particular keycap to press. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously).
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:
File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose System → Preferences → Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose Applications → Accessories → Character Map from the main menu bar. Next, choose Search → Find… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose Edit → Paste from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.
Mono-spaced Bold Italic or Proportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release.
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
Publican is a DocBook publishing system.

1.2. Pull-quote Conventions

Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in mono-spaced roman and presented thus: 
books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs
Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows: 
package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }
}

1.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note

Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration.

Warning

Warnings should not be ignored. Ignoring warnings will most likely cause data loss.

2. We Need Feedback!

You should over ride this by creating your own local Feedback.xml file.

Chapter 1. Word Usage

Glossary
A guide to common words and their ambiguities

Glossary

A

a.m.
Avoid if at all possible. When presenting specific dates and times numerically, ISO Standard 8601 is our guide. For times, this means the 24-hour clock is preferred. 14:35 not 2:35 pm.
If the 12-hour clock must be used, the abbreviations for "ante meridiem" and "post meridiem" should be presented without punctuation and in small caps, as follows: "am" and "pm".
If small caps are unavailable, lowercase is preferred to uppercase.
abort
To stop a program or function before it has finished naturally. The term abort refers to both requested and unexpected terminations. For example, many applications let you abort a search or a print job. On the other hand, programs can abort unexpectedly for any of the following reasons:
  • bugs in the software
  • unexpected input that the program cannot handle
  • hardware malfunction
above
Do not use to refer to information mentioned previously. When documents are converted to HTML, the information may no longer be ‘above’. Use a cross-reference instead.
acronyms
An acronym is a word formed from the initial letters of a name, such as ROM for Read Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. Note that an acronym is pronounceable as a word. Compare this to an initialism, which is also formed in a similar fashion to an acronym, but in which each letter is pronounced separately.
Spell out the acronym or initialism before using it in text, such as "The Embedded DevKit (EDK)...". Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version — for example, ‘central processing unit (CPU)’.
To form the plural of an acronym, add a trailing, lower-case "s", e.g., ROMs, PINs.
alternate
Don’t use this to mean ‘an alternative to something’. ‘Alternate’ (vb.) means to change between two states or options, etc. If you mean ‘another way of doing something’, use ‘an alternative method is to…’.
appendixes
Correct. Do not use ‘appendices’.
applications
When used as a proper name, use the capitalization of the product. When used as a command, use lowercase as appropriate, such as ‘To start GCC, type gcc’.
Note: ‘vi’ is always lowercase.
architecture
A design. The term architecture can refer to either hardware or software, or to a combination of hardware and software. The architecture of a system always defines its broad outlines, and may define precise mechanisms as well.
An open architecture allows the system to be connected easily to devices and programs made by other manufacturers. Open architectures use off-the-shelf components and conform to approved standards. A system with a closed architecture, on the other hand, has a proprietary design.
At this point in time
Do not use. Use either ‘now’ or ‘at this time’.
ATM
Short for Asynchronous Transfer Mode, a network technology based on transferring data in cells or packets of a fixed size. The cell used with ATM is relatively small compared to units used with older technologies. The small, constant cell size allows ATM equipment to transmit video, audio, and computer data over the same network, and assure that no single type of data hogs the line.
auto-detect
Correct. Do not use ‘autodetect’.
automagic
Also, automagical. This is slang. Do not use.

B

back end and back-end
‘Back end’ is a noun, ‘back-end’ is an adjective. Refers to software that performs the final stages of a process, or tasks that are not visible to the user.
Example of noun — ‘Each back end provides a set of calls.’
Example of adjective — ‘When the back-end database processes a search operation…’
Do not use ‘backend’ as noun or adjective.
back up
Depending on usage, this could appear in any of three ways:
  • Verb: You should always back up important files.
  • Noun: You should create a backup of your important files.
  • Adjective: The back-up copies of important files should be kept in a secure location.
background
  • Multitasking computers are capable of executing several tasks, or programs, at the same time. In some multitasking systems, one of the processes is called the foreground process , and the others are called background processes.
    The foreground process is the one that accepts input from the keyboard, mouse, or other input device. Background processes cannot accept interactive input from a user, but they can access data stored on a disk and write data to the video display. For example, some word processors print files in the background, enabling you to continue editing while files are being printed. This is called print spooling . In addition, many communications programs are designed to run in the background. Background processes generally have a lower priority than foreground processes so that they do not interfere with interactive applications.
  • The area of a display screen not covered by characters and graphics. The background is like a canvas on top of which characters and graphics are placed. Some monitors allow you to control the color or shading of the background.
backup
This is a noun. You create ‘backup’ files; you do not create ‘back up’ files.
backward
Correct. Avoid using backwards unless you are stating that something has ‘backwards compatibility’.
backwards compatibility
Correct.
bandwidth
  • A range within a band of frequencies or wavelengths.
  • The amount of data that can be transmitted in a fixed amount of time. For digital devices, the bandwidth is usually expressed in bits per second (bps) or bytes per second (Bps). For analog devices, the bandwidth is expressed in cycles per second, or Hertz (Hz).
basically
Do not use. For example, removing the word ‘basically’ in the following sentence strengthens it: ‘This is how it is basically done’.
because or since
Don’t use ‘since’ to mean ‘because’, it is ambiguous. Use ‘because’ to refer to a reason. Use ‘since’ to refer to the passage of time.
behavior
Correct. Do not use ‘behaviour’.
below
Do not use to refer to information mentioned ‘below’. When documents are converted to HTML, the information may no longer be ‘below’. Use a cross-reference instead.
BIND
Correct. Do not use Bind.
BIOS
Correct. If pluralization is needed, BIOSes is correct.
bit rate
Correct. Do not use ‘bitrate’.
Boolean
Correct. Do not use ‘boolean’.
boot
  • (v) To load the first piece of software that starts a computer. Because the operating system is essential for running all other programs, it is usually the first piece of software loaded during the boot process.
    Boot is short for bootstrap, which in olden days was a strap attached to the top of your boot that you could pull to help get your boot on. Hence, the expression ‘pull oneself up by the bootstraps’. Similarly, bootstrap utilities help the computer get started.
  • (n) Short for bootstrap, the starting-up of a computer, which involves loading the operating system and other basic software. A cold boot is when you turn the computer on from an off position. A warm boot is when you reset a computer that is already on.
boot disk
Correct. Two words. ‘Boot diskette’ should not be used.
boot loader
Correct. Two words. Do not use ‘bootloader’.
bottleneck
Correct. Do not use ‘bottle neck’ or ‘bottle-neck’.
A bottleneck refers to the delay in transmission of data through the circuits of a computer’s microprocessor or over a TCP/IP network. The delay typically occurs when a system’s bandwidth cannot support the amount of information being relayed at the speed it is being processed. There are, however, many factors that can create a bottleneck in a system.
bpp
Stands for bits per pixel. All letters are lowercase (unless at the beginning of a sentence, obviously). Example, ‘16 bpp,’ not ‘16bpp’.
bring up
Do not use. Use ‘open’ instead.
broadcast
To simultaneously send the same message to multiple recipients. Broadcasting is a useful feature in email systems. It is also supported by some fax systems.
In networking, a distinction is made between broadcasting and multicasting. Broadcasting sends a message to everyone on the network whereas multicasting sends a message to a select list of recipients.
bug fix
Correct. Do not use ‘bugfix’.
built-in
Correct. Do not use ‘builtin’.
bunches of
Do not use. Use ‘many’ instead.
button
Refer to a GUI button as a ‘button’, not a ‘pushbutton’ or ‘push-button’.
Ordinarily you would not need to include the text ‘button’ in a procedure or description. For example, ‘Click OK to continue’. is perfectly acceptable. It may be necessary to distinguish between buttons and links, for example, ‘Click the Unload button’.

C

can/may
Use ‘can’ to describe actions or conditions that are possible. Use ‘may’ only to describe situations where permission is being given. If either ‘can,’ ‘could,’ or ‘may’ apply, use ‘can’ — it is less tentative.
canceled
Correct. Do not use ‘cancelled’.
cannot
Correct. Do not use ‘can not’.
cd or CD
When referring to the change directory command, use cd.
When referring to a compact disk, use CD, such as ‘Insert the CD into the CD-ROM drive’. The plural is ‘CDs’.
When referring to the optical drive, use CD-ROM drive. Do not use ‘cdrom,’ ‘CD-Rom,’ ‘CDROM,’ ‘cd-rom’ or any other variation. The plural is ‘CD-ROM drives’.
characters
Do not use ‘characters’ when you should use ‘bytes’. In English, bytes and characters can be used interchangeably; in other languages a single character may consist of multiple bytes.
In computer software, any symbol that requires one byte of storage. This includes all the ASCII and extended ASCII characters, including the space character. In character-based software, everything that appears on the screen, including graphics symbols, is considered to be a character. In graphics-based applications, the term character is generally reserved for letters, numbers, and punctuation.
check
Do not use. Use verify, make sure, ensure, or read, depending on the context.
checkbox
Correct. Do not use ‘check box’.
chipset
Correct. Do not use ‘chip set’.
ciphertext
Correct. Do not use "cipher text" or "cipher-text" or other variants.
clear text
Do not use. Use plain text instead.
click
Use when referring to a GUI control button. For example, ‘Click OK’ or ‘Click the Unload button’.
For keyboard instructions, see press.
client-side/client side
Careful here. For example: Windbind is a client-side service used to connect to Windows NT servers. Windbind runs on the client side of a client/server Samba implementation. See server-side/server side.
client/server architecture
A network architecture in which each computer or process on the network is either a client or a server. Servers are powerful computers or processes dedicated to managing disk drives (file servers), printers (print servers), or network traffic (network servers ). Clients are PCs or workstations on which users run applications. Clients rely on servers for resources, such as files, devices, and even processing power.
Another type of network architecture is known as a peer-to-peer architecture because each node has equivalent responsibilities. Both client/server and peer-to-peer architectures are widely used, and each has unique advantages and disadvantages.
Client/server architectures are sometimes called two-tier architectures.
clobber or clobbered
These words should be avoided (except if ‘clobber’ is the actual name of something). Use ‘altered,’ ‘invalidated,’ or ’overwritten’ — whichever is appropriate in the specific context.
clustering
Connecting two or more computers together in such a way that they behave like a single computer. Clustering is used for parallel processing, load balancing and fault tolerance.
Clustering is a popular strategy for implementing parallel processing applications because it enables companies to leverage the investment already made in PCs and workstations. In addition, it’s relatively easy to add new CPUs simply by adding a new PC to the network.
code
Only use as a noun, not a verb. Use ‘write’ for a verb.
color
Correct. Do not use ‘colour’.
combo-box
Correct. Do not use ‘combobox’.
comma-delimited
A data format in which each piece of data is separated by a comma. This is a popular format for transferring data from one application to another, because most database systems are able to import and export comma-delimited data.
command
An instruction to a computer or device to perform a specific task. Commands come in different forms. They can be:
  • special words (keywords) that a program understands
  • function keys
  • choices in a menu
  • buttons or other graphical objects on your screen
Every program that interacts with people responds to a specific set of commands. The set of commands and the syntax for entering them is called the user interface and varies from one program to another.
Another word for command is directive.
command button
Use button instead.
command language
The programming language through which a user communicates with the operating system or an application. For example, the DOS command language includes the commands DIR, COPY, and DEL, to name a few. The part of an operating system that responds to operating system commands is called the command processor.
With graphical user interfaces, the command language consists of operations you perform with a mouse or similar input device.
command line
Correct. Do not use ‘command-line’ or ‘commandline’.
The line on the display screen where a command is expected. Generally, the command line is the line that contains the most recently displayed command prompt.
command processor
The part of the operating system that receives and executes operating system commands. Every operating system has a command processor. When the shell prompt is displayed, the command processor is waiting for a command. After you enter a command, the command processor analyzes the syntax to make sure the command is valid, and then either executes the command or issues an error warning. For operating systems with a graphical user interface, the command processor interprets mouse operations and executes the appropriate command.
Another term for command processor is command line interpreter.
command prompt
Do not use. Use ‘shell prompt’ instead.
command-driven
Correct. Do not use ‘command driven’ or ‘commanddriven’.
Refers to programs and operating systems that accept commands in the form of special words or letters. In contrast, programs that allow you to choose from a list of options in a menu are said to be menu driven. Command-driven software is often more flexible than menu-driven software, but it is more difficult to learn.
component
  • A small binary object or program that performs a specific function and is designed in such a way to easily operate with other components and applications. Increasingly, the term is being used interchangeably with applet.
  • A part of a device.
configuration file
A file that contains configuration information for a particular program. When the program is executed, it consults the configuration file to see what parameters are in effect.
connectivity
A computer buzzword that refers to a program or device’s ability to link with other programs and devices. For example, a program that can import data from a wide variety of other programs and can export data in many different formats is said to have good connectivity. On the other hand, computers that have difficulty linking into a network (many laptop computers, for example) have poor connectivity.
contractions
Do not use. Contractions are a mark of informal writing, and should be avoided when writing policy manuals or other more formal types of manuals. They also cause problems for translation.
control character
A special, non-printing character that begins, modifies, or ends a function, event, operation or control operation. The ASCII character set defines 32 control characters. Originally, these codes were designed to control teletype machines. Now, however, they are often used to control display monitors, printers, and other modern devices.
control key
Use Ctrl instead, such as ‘To save the program, press Ctrl+Z’.
Control Panel or control-panel
When referring to a window, use Control Panel, such as ‘From the Settings menu, select Control Panel’. When referring to the command to start the control panel from X, use control-panel.
control program
A program that enhances an operating system by creating an environment in which you can run other programs. Control programs generally provide a graphical interface and enable you to run several programs at once in different windows.
Control programs are also called operating environments.
convert
To change data from one format to another.
cookie
A message given to a web browser by a web server. The browser stores the message in a text file called cookie.txt. The message is then sent back to the server each time the browser requests a page from the server.
The main purpose of cookies is to identify users and possibly prepare customized web pages for them. When you enter a website using cookies, you may be asked to fill out a form providing such information as your name and interests. This information is packaged into a cookie and sent to your web browser which stores it for later use. The next time you go to the same website, your browser will send the cookie to the web server. The server can use this information to present you with custom web pages. So, for example, instead of seeing just a generic welcome page you might see a welcome page with your name on it.
The name ‘cookie’ derives from UNIX objects called magic cookies. These are tokens that are attached to a user or program and change depending on the areas entered by the user or program. Cookies are also sometimes called ‘persistent cookies’ because they typically stay in the browser for long periods of time.
corrupted
Refers to data that has been damaged in some way.
CR
Use if referring to code, such as ‘Type CR at the end of each line…’. If referring to the keyboard key, use either Enter or Return, depending upon the platform.
cross-platform
Correct. Do not use ‘crossplatform’ or ‘cross platform’.
Refers to the capability of software or hardware to run identically on different platforms.
cross-site scripting
Correct. When referring to cross-site scripting attacks, use ‘cross-site scripting attack’. Acceptable use is also ‘cross-site (XSS) scripting attack’.
Cygmon
Correct. Do not use ‘CygMon,’ ‘cygmon,’ or ‘CYGMON’. An exception is if a command is being typed (such as cygmon).
Refer to it as ‘Cygmon: a ROM monitor,’ not ‘Cygmon: the Cygnus ROM monitor" or ‘Cygmon: the ROM monitor’.

D

daisy chain
  • (n) A hardware configuration in which devices are connected one to another in a series. The SCSI interface, for example, supports a daisy chain of up to 7 devices.
  • (v) To connect devices in a daisy chain pattern.
data
  • (1) Distinct pieces of information, usually formatted in a special way. All software is divided into two general categories: data and programs. Programs are collections of instructions for manipulating data.
    Data can exist in a variety of forms — as numbers or text on pieces of paper, as bits and bytes stored in electronic memory, or as facts stored in a person’s mind.
    Strictly speaking, data is the plural of datum, a single piece of information. In practice, however, people use data as both the singular and plural form of the word.
  • (2) The term data is often used to distinguish binary machine-readable information from textual human-readable information. For example, some applications make a distinction between data files (files that contain binary data) and text files (files that contain ASCII data).
  • (3) In database management systems, data files are the files that store the database information, whereas other files, such as index files and data dictionaries, store administrative information, known as metadata.
data mirroring
The act of copying data from one location to a storage device in real time. Because the data is copied in real time, the information stored from the original location is always an exact copy of the data from the production device.
Data mirroring is useful in the speedy recovery of critical data after a disaster. Data mirroring can be implemented locally or offsite at a completely different location.
data type
Correct. Do not use ‘datatype’ or ‘data-type"
dates
Use the April 1, 1999 or 1 APR 1999 format for dates.
debug
To find and remove errors (bugs) from a program or design.
deleting
When referring to removing software from a system use ‘uninstall’.
denial of service (DoS)
Correct. Do not use ‘denial-of-service’ or ‘Denial of Service’.
desktop
Correct. Do not use ‘desk top’ or desk-top’.
In graphical user interfaces, a desktop is the metaphor used to portray file systems. Such a desktop consists of pictures, called icons, that show cabinets, files, folders, and various types of documents (that is, letters, reports, pictures). You can arrange the icons on the electronic desktop just as you can arrange real objects on a real desktop — moving them around, putting one on top of another, reshuffling them, and throwing them away.
device
Any machine or component that attaches to a computer. Examples of devices include disk drives, printers, mice, and modems. These particular devices fall into the category of peripheral devices because they are separate from the main computer.
Most devices, whether peripheral or not, require a program called a device driver that acts as a translator, converting general commands from an application into specific commands that the device understands.
dial-up access
Refers to connecting a device to a network via a modem and a public telephone network. Dial-up access is really just like a phone connection, except that the parties at the two ends are computer devices rather than people. Because dial-up access uses normal telephone lines, the quality of the connection is not always good and data rates are limited. In the past, the maximum data rate with dial-up access was 56 Kbps (56,000 bits per second), but new technologies such as ISDN are providing faster rates.
An alternative way to connect two computers is through a leased line, which is a permanent connection between two devices. Leased lines provide faster throughput and better quality connections, but they are also more expensive.
dialog box
Correct. Do not use ‘dialog’ on its own. For example, ‘Use the Project Preferences dialog box to specify project-specific parameters’.
different
Use ‘different from’ rather than ‘different than’ when the next part of the sentence is a noun or pronoun (that is, two things are being compared). For example:Form 123 is different from Form 124.
disc
This is correct when referring to a compact disc, but not a diskette or hard disk.
disk
This is correct when referring to a hard disk, but not a compact disc or floppy diskette.
disk label
Correct. Do not write as one word.
diskette
This is correct when referring to a floppy diskette or a boot diskette.
DNS
Short for Domain Name System (or Service), an Internet service that translates domain names into IP addresses.
documentation
When referring to the current manual set, use ‘documentation’. For example, ‘This manual is also available as part of our online documentation’. When referring to another manual, quote the title of the manual, such as ‘For further information, see the Getting Started Guide’.
domain name
Correct. Do not use "domainname" or "domain-name".
A name that identifies one or more IP addresses. For example, the domain name microsoft.com represents about a dozen IP addresses. Domain names are used in URLs to identify particular web pages. For example, in the URL http://www.redhat.com/docs, the domain name is redhat.com.
double-click
Correct. Do not use "double click".
download
Correct. Do not use "down load" or "down-load".
dual-boot
Do not use dualboot or dual boot.
dude
Slang. Do not use.
DVD writer
Correct. Do not use DVD burner or CD burner (use CD writer in that case). Reason, it is colloquial.

E

e.g.
Spell it out: "For example".
earlier
Refer to later
Emacs
If referring to the program, use ‘Emacs’. For example, ’Source-Navigator supports Emacs or vi commands’. If referring to the shell prompt command, use ‘emacs’. For example, ‘At the prompt, type emacs’. The proper name is: GNU Emacs.
email
Correct. Do not use ‘E-mail’ or ‘e-mail’.
embedded object
An object created with one application and embedded into a document created by another application. Embedding the object, rather than simply inserting or pasting it, ensures that the object retains its original format. In fact, you can modify the embedded object with the original program.
encryption
The translation of data into a secret code. Encryption is the most effective way to achieve data security. To read an encrypted file, you must have access to a secret key or password that enables you to decrypt it. Unencrypted data is called plain text ; encrypted data is referred to as ciphertext.
There are two main types of encryption: asymmetric encryption (also called public-key encryption) and symmetric encryption.
ensure
This means ‘to make sure, certain, or safe; guarantee’. For example, ‘Perform the following steps to ensure a network and serial connection’.
enter
When referring to the keyboard key, use Enter. If referring to the keyboard key on Solaris, use Return.
When referring to typing a command, use ‘type’ instead, such as ‘To open Source-Navigator from the command line, type snavigator’.
When typing information into a single-field dialog box, ‘enter’ means ‘type and press Enter’. An example is ‘Enter the license number’. For multi-field dialog boxes, see type.
environment
The state of a computer, usually determined by which programs are running and basic hardware and software characteristics. For example, when one speaks of running a program in a UNIX environment, it means running a program on a computer that has the UNIX operating system.
One ingredient of an environment, therefore, is the operating system. But operating systems include a number of different parameters. For example, many operating systems allow you to choose your command prompt or a default command path. All these parameters taken together constitute the environment.
Another term for environment in this sense is platform.
essentially
Do not use. See basically.
Ethernet
A local-area network (LAN) architecture developed by Xerox Corporation in cooperation with DEC and Intel in 1976. Ethernet uses a bus or star topology and supports data transfer rates of 10 Mbps. The Ethernet specification served as the basis for the IEEE 802.3 standard, which specifies the physical and lower software layers. Ethernet uses the CSMA/CD access method to handle simultaneous demands. It is one of the most widely implemented LAN standards.
A newer version of Ethernet, called 100Base-T (or Fast Ethernet), supports data transfer rates of 100 Mbps. And the newest version, Gigabit Ethernet supports data rates of 1 gigabit (1,000 megabits) per second.
event
An action or occurrence detected by a program. Events can be user actions, such as clicking a mouse button or pressing a key, or system occurrences, such as running out of memory.
exclamation points (!)
Do not use them at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command.
execute
Same as run. Execute means to perform an action, as in executing a program or a command.
Exif
Correct. Do not use ‘EXIF’. Exif is an image file format specification that enables metadata tags to be added to existing JPEG, TIFF and RIFF files. Sometimes to referred to as ‘Exif Print’.
extranet
A new buzzword that refers to an intranet that is partially accessible to authorized outsiders. Whereas an intranet resides behind a firewall and is accessible only to people who are members of the same company or organization, an extranet provides various levels of accessibility to outsiders. You can access an extranet only if you have a valid username and password, and your identity determines which parts of the extranet you can view.

F

fail over
When used as a verb, fail over is two words since there can be different tenses such as failed over.
failover
When used as a noun, a failover is a backup operation that automatically switches to a standby database, server or network if the primary system fails or is temporarily shut down for servicing. Failover is an important fault tolerance function of mission-critical systems that rely on constant accessibility. Failover automatically and transparently to the user redirects requests from the failed or down system to the backup system that mimics the operations of the primary system.
FAQ
When referring to a Frequently Asked Questions (FAQ) section of content, refer to it as ‘an FAQ’ (to be read as ‘an F-A-Q) not ‘a FAQ’.
fault tolerance
The ability of a system to respond gracefully to an unexpected hardware or software failure. There are many levels of fault tolerance, the lowest being the ability to continue operation in the event of a power failure. Many fault-tolerant computer systems mirror all operations — that is, every operation is performed on two or more duplicate systems, so if one fails the other can take over.
fiber
Correct. Despite the alternative spelling used in Fibre Channel, "fiber" is the correct form to use in all other cases.
Fibre Channel
A serial data transfer architecture developed by a consortium of computer and mass storage device manufacturers and now being standardized by ANSI. The most prominent Fibre Channel standard is Fibre Channel Arbitrated Loop (FC-AL). FC-AL was designed for new mass storage devices and other peripheral devices that require very high bandwidth. Using optical fibre to connect devices, FC-AL supports full-duplex data transfer rates of 100MBps. FC-AL is compatible with, and is expected to eventually replace, SCSI for high-performance storage systems.
field
Do not use ‘field’ on its own. Instead name the field, such as ‘In the Name field, type the name of the program to debug’.
file name
Correct. Do not use ‘filename’.
file system
Correct. Do not use ‘filesystem’.
The system that an operating system or program uses to organize and keep track of files. For example, a hierarchical file system is one that uses directories to organize files into a tree structure.
Although the operating system provides its own file management system, you can buy separate file management systems. These systems interact smoothly with the operating system but provide more features, such as improved backup procedures and stricter file protection.
file system — flat file system
A system of organizing files in an operating system in which all files are stored in a single directory. In contrast to a hierarchical file system, in which there are directories and subdirectories and different files can have the same name as long as they are stored in different directories, in a flat file system every file must have a different name because there is only one list of files. Early versions of the Macintosh and DOS operating systems used a flat file system. Modern commercial operating systems use a hierarchical file system.
file system — hierarchical file system
Refers to systems that are organized in the shape of a pyramid, with each row of objects linked to objects directly beneath it.
firmware
Correct. Do not use ‘firm ware’ or ‘firm-ware’.
Software (programs or data) that has been written onto read-only memory (ROM). Firmware is a combination of software and hardware. ROMs, PROMs and EPROMs that have data or programs recorded on them are firmware.
floating point
Correct. Do not hyphenate.
floppy disk
Do not use. Instead, use "diskette", and also state the size of the diskette, such as "3.5in. diskette".
floppy drive
Do not use. Instead use "diskette drive".
foreground
  • In multiprocessing systems, the process that is currently accepting input from the keyboard or other input device is sometimes called the foreground process.
  • On display screens, the foreground consists of the characters and pictures that appear on the screen. The background is the uniform canvas behind the characters and pictures.
FORTRAN
Correct. Do not use ‘Fortran’.
forward
Correct. Avoid using ‘forwards’.
FQDN
A fully qualified domain name consists of a host and domain name, including top-level domain. For example, www.redhat.com is a fully qualified domain name. www is the host, redhat is the second-level domain, and.com is the top level domain.
A FQDN always starts with a host name and continues all the way up to the top-level domain name, so www.parc.xerox.com is also a FQDN.
front end and front-end
‘Front end’ is a noun, ‘front-end’ is an adjective.
Example of noun — ‘PRCS is a front end for a version control toolset.’
Example of adjective — ‘This chapter explains how to use the front-end API functions.’
Do not use ‘frontend’ as noun or adjective.
FTP
Use all caps when referring to the protocol. Use lowercase when referring to the command-line program.
Futexes
Correct. "Futex" is an abbreviation of "fast user-space mutex". Consequently, "futexes" is the correct plural form.
Fuzzy
Correct only when referring to fuzzy searches. Refer to AvoidingSlang for details and examples.

G

g++ or G++
When referring to the command, use g++. When referring to the program, use G++.
gas or GAS
When referring to the command, use gas. When referring to the program, use GAS.
Gbps
Short for Gigabits per second, a data transfer speed measurement for high-speed networks such as Gigabit Ethernet. When used to describe data transfer rates, a gigabit equals 1,000,000,000 bits.
gcc or GCC
When referring to the command, use gcc. When referring to the program, use GCC.
gcj or GCJ
When referring to the command, use gcj. When referring to the program, use GCJ.
gdb or GDB
When referring to the command, use gdb. When referring to the program, use GDB.
GDBTK
Do not use. Use ‘Insight’ instead. GDBTK is an obsolete name for the GNU debugger.
GID
Abbreviation for Group ID. Do not use ‘gid’.
gigabyte
2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. When abbreviating "gigabyte", use "GB".
GIMP
Acronym for GNU Image Manipulation Program. Do not use ’Gimp’ or ‘gimp’.
GNOME
Correct. Do not use ‘gnome,’ ‘Gnome,’ or other variants.
GNU
Recursive acronym for ‘GNU’s Not UNIX’. Do not use ‘Gnu’ or ’gnu’.
GNU Emacs
See Emacs.
got
Do not use.
GPL
Acronym for General Public License. Do not use ‘Gpl’ or ’gpl’.
granularity
The extent to which a system contains separate components (like granules). The more components in a system — or the greater the granularity — the more flexible it is.
gray
Correct. This option will be grayed out’. Do not use ‘grey’.
GRUB
Correct. All caps. Do not use ‘Grub’.
GTK+
Acronym for GIMP Tool Kit. Do not use ‘GTK,’ ‘Gtk,’ or ’gtk’.

H

hard disk
Correct. Do not use ‘harddisk’ or ‘hard-disk’.
hard drive
Correct. Do not use ‘harddrive’ or ‘hard-drive’.
hardcode
Do not use. Use "hard-coded" (adjective) or "hard code" (verb).
hardcopy
Do not use. Instead, use ‘printed’. For example: ‘To order the printed documentation…’.
he/she
Do not use. See you.
high-availability
Correct. Do not use ‘high availability’.
homepage
This is now preferred to the older, two-word presentation: ‘home page’.
Like ‘website’, and unlike ‘web page’ (where standard spelling still prefers the two-word version), this term has mostly made the transition to a single-word form.
This said, the term itself (regardless of spelling) should be used with care.
Homepage has two common meanings: the default data loaded into a browser window when the browser launches and the default data loaded when making an http connection to a web server that only specifies the FQDN of the server (i.e., doesn't request a particular URI). The similarity and difference between these two common meanings has obvious potential for both confusion and error.
If there is any possibility of confusion, re-write to avoid the term.
hostname
Correct. One word, lowercase. Capitalize when used at the beginning of a sentence, but try to reword the sentence to avoid this.
hot add
Correct. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use ‘hotadd’ or ‘hot-add’.
hot plug
Correct. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use ‘hotplug’ or ‘hot-plug’.
hot swap
Correct. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use ‘hotswap’ or ‘hot-swap’.
HOWTO
Correct. Do not use ‘howto’ or ‘Howto’. The plural is ’HOWTOs’.
HTML
When referring to the language, use ‘HTML,’ such as ‘To see the HTML version of this documentation…’. When referring to a web page extension, use ‘html,’ such as ‘The main page is index.html’.
Hyper-Threading
Hyper-Threading is Intel's implementation of simultaneous multithreading. Do not use hyperthreading or hyper-threading. If you are not referring specifically to Intel's implementation, use ‘simultaneous multithreading’ or ‘SMT’ instead.
hypervisor
Correct. Do not use ?HyperVisor or Hyperviser.

I

i.e.
Spell it out: ‘That is’.
I/O
Correct. "I/O" is short for input/output (pronounced "eye-oh"). The term I/O is used to describe any program, operation or device that transfers data to or from a computer and to or from a peripheral device. Every transfer is an output from one device and an input into another. Devices such as keyboards and mice are input-only devices, while devices such as printers are output-only. A writable CD is both an input and an output device.
if you want
Do not use. For example, instead of saying ‘If you want to perform an action…’, say ’To perform an action…’.
if you wish
Do not use. For example, instead of saying ‘If you wish to perform an action…’, say ’To perform an action…’.
in concert with
Do not use. Instead, say ‘with’. For example, change ‘Use gcov in concert with GCC to analyze…’ to ‘Use gcov with GNU CC to analyze…’.
indexes
Correct. Do not use ‘indices’.
inline
Correct. Do not use ‘in-line’.
insecure
Correct. Do not use ‘nonsecure’ or ‘non-secure’.
installation program
Correct. Do not use ‘installer’.
installer
Do not use ‘installer’. Use ‘installation program’ instead.
insure
"Insure’ refers to insurance. Use ensure.
integrated
  • A popular computer buzzword that refers to two or more components merged together into a single system. For example, any software product that performs more than one task can be described as integrated.
  • Increasingly, the term integrated software is reserved for applications that combine word processing, database management, spreadsheet functions, and communications into a single package.
interesting
Avoid using, as this is a substitute for showing the reader why something is of interest. For example, change ‘It is interesting to note…’. to ‘Note…’.
Internet or internet
Use ‘Internet’ when referring to a large internet comprising large national backbone nets and various regional and local networks worldwide: ‘The Internet used the Internet Protocol suite’.
Use internet when referring to a collection of networks that function as a single larger virtual network.
Intranet or intranet
Internets are networks based on TCP, IP and various other protocols. An internet belonging to an organization, usually a corporation, accessible only by the organization’s members, employees, or others with authorization. An intranet’s websites look and act just like any other websites, but the firewall surrounding an intranet fends off unauthorized access.
Like the Internet itself, intranets are used to share information. Secure intranets are now the fastest-growing segment of the Internet because they are much less expensive to build and manage than private networks based on proprietary protocols.
IP
Correct. "IP" is short for "Internet Protocol". Capitalize both letters.
IP Masquerade
A Linux networking function. IP Masquerade, also called IPMASQ or MASQ, allows one or more computers in a network without assigned IP addresses to communicate with the Internet using the Linux server’s assigned IP address. The IPMASQ server acts as a gateway, and the other devices are invisible behind it, so to other machines on the Internet the outgoing traffic appears to be coming from the IPMASQ server and not the internal PCs.
Since IPMASQ is a generic technology the server can be connected to other computers through LAN technologies like Ethernet, Token Ring, and FDDI, as well as dialup connections like PPP or SLIP.
IP switching
A new type of IP routing developed by Ipsilon Networks, Inc. Unlike conventional routers, IP switching routers use ATM hardware to speed packets through networks. Although the technology is new, it appears to be considerably faster than older router techniques.
IPsec
IPsec stands for Internet Protocol Security. According to its RFC, IPsec should be used. Do not use ‘IPSec’.
ISV
Short for Independent Software Vendor, a company that produces software.
it’s and its
‘It’s’ is a contraction for ‘it is,’ use ‘it is’ instead of ‘it’s’. Use ‘its’ as a possessive pronoun (for example, ‘the store is known for its low prices’).

J

jabber
  • An error in which a faulty device (usually a NIC ) continuously transmits corrupted or meaningless data onto a network. This may halt the entire network from transmitting data because other devices will perceive the network as busy.
  • a sent data packet greater than the maximum 1518 bytes specified in IEEE 802.3. To prevent this, jabber control should be added to the hardware to make the circuitry incapable of sending information for more than 150 milliseconds (approximately 1500 bytes).
job
A task performed by a computer system. For example, printing a file is a job. Jobs can be performed by a single program or by a collection of programs.
just
Use sparingly. In the phrase, ‘Just point your browser to…’. the word ‘just’ can be omitted.
JVM
Acronym for Java Virtual Machine. Do not use Jvm or jvm.

K

Kbps
Short for kilobits per second, a measure of data transfer speed. Modems, for example, are measured in Kbps. Note that one Kbps is 1,000 bits per second, whereas a KB (kilobyte) is 1,024 bytes. Data transfer rates are measured using the decimal meaning of K whereas data storage is measured using the powers-of-2 meaning of K. Technically, kbps should be spelled with a lowercase k to indicate that it is decimal but almost everyone spells it with a capital K.
kerberize
Incorrect. Do not use "kerberize", "kerberized", or other variants to refer to applications or services that use Kerberos authentication. Refer to such applications as "Kerberos-aware" or "Kerberos-enabled", or rewrite the sentence.
kernel
The central module of an operating system. It is the part of the operating system that loads first, and it remains in main memory. Because it stays in memory, it is important for the kernel to be as small as possible while still providing all the essential services required by other parts of the operating system and applications. Typically, the kernel is responsible for memory management, process and task management, and disk management.
kernel-space
Correct. Do not use ‘kernelspace’ or ‘kernel space’.
keyboard key
When referring to a keyboard key, it is uppercase, singular, and the word ‘key’ is not necessary, such as ‘To exit, press X’. When the Ctrl or Alt keys are needed, use a plus sign between the keys, such as ‘To save the file, press Ctrl+S’.
See also spacebar.
kill
If terminating a UNIX process, use kill. For example, "To terminate the process, type kill -9 number". If terminating a Windows process, use "terminate". For example, "To terminate the process, press Q."
kilobit
Correct. The correct abbreviation is ‘Kb,’ not ‘KB’ or ‘kb’.
kilobyte
Correct. The correct abbreviation is ‘KB,’ not ‘Kb’ or ‘kb’.
knowledgebase
Incorrect. Use "knowledge base".

L

LAN
Correct. This is an acronym for Local Area Network. Do not use Lan or lan.
latency
  • In general, the period of time that one component in a system is spinning its wheels waiting for another component. Latency, therefore, is wasted time. For example, in accessing data on a disk, latency is defined as the time it takes to position the proper sector under the read/write head.
  • In networking, the amount of time it takes a packet to travel from source to destination. Together, latency and bandwidth define the speed and capacity of a network.
later/newer
When referring to more recent versions of a product, package, or other software, use "later", and not "newer" or any other terms. The converse applies when referring to earlier versions. That is, use "earlier", and not "older" or any other terms.
For example, "MyProduct 5.0 and later use the Wonderful system of synchronization. Earlier releases of MyProduct use the Mediocre system."
launch
To start a program.
leave out
Do not use. Use ‘omit’ instead.
left-click
Correct. Do not use ‘left click’.
license
Commonwealth English still treats license and licence as different words: licence is the noun, license is the verb. US English does not, spelling both the noun and the verb ‘license’.
US English still recognises ‘licence’ as a legitmate spelling. It recognises it as a British spelling, however, not as a way of distinguishing the noun from the verb. We follow US English practice and use a single spelling for both the noun and the verb.
life-cycle
When referring to a software life-cycle, use life-cycle. Do not use ‘lifecycle’ or ‘life cycle’.
like
Do not use as a conjunction; use ‘such as’ instead. Correct: ‘Open a text editor, such as Pico’. Incorrect: ‘Open a text editor, like Pico’.
list
When referring to the UNIX command, use ls instead. See ls for more information.
load
  • To install. For example, to load a disk means to mount it in a disk drive.
  • To copy a program from a storage device into memory. Every program must be loaded into memory before it can be executed. Usually the loading process is performed invisibly by a part of the operating system called the loader. You simply enter the name of the program you want to run, and the operating system loads it and executes it for you.
  • In programming, load means to copy data from main memory into a data register.
  • In networking, load refers to the amount of data (traffic) being carried by the network.
load balancing
Distributing processing and communications activity evenly across a computer network so that no single device is overwhelmed. Load balancing is especially important for networks where it’s difficult to predict the number of requests that will be issued to a server. Busy websites typically employ two or more web servers in a load balancing scheme. If one server starts to get swamped, requests are forwarded to another server with more capacity. Load balancing can also refer to the communications channels themselves.
local-area network
See LAN.
log in
A verb used to refer to the act of logging in. Do not use "login", "logon", or other variants. For example, "When starting your computer, you are requested to log in...".
log on
To make a computer system or network recognize you so that you can begin a computer session. Most personal computers have no log-on procedure — you just turn the machine on and begin working. For larger systems and networks, however, you usually need to enter a username and password before the computer system will allow you to execute programs.
log out
To end a session at the computer. For personal computers, you can log out simply by exiting applications and turning the machine off. On larger computers and networks, where you share computer resources with other users, there is generally an operating system command that lets you log off.
logging in
Refers to the log in process.
logical topology
Also called signal topology. Every LAN has a topology, or the way that the devices on a network are arranged and how they communicate with each other. The way that the workstations are connected to the network through the actual cables that transmit data — the physical structure of the network — is called the physical topology. The logical topology, in contrast, is the way that the signals act on the network media, or the way that the data passes through the network from one device to the next without regard to the physical interconnection of the devices.
Logical topologies are bound to the network protocols that direct how the data moves across a network. The Ethernet protocol is a common logical bus topology protocol. LocalTalk is a common logical bus or star topology protocol. IBM’s Token Ring is a common logical ring topology protocol.
A network’s logical topology is not necessarily the same as its physical topology. For example, twisted pair Ethernet is a logical bus topology in a physical star topology layout. While IBM’s Token Ring is a logical ring topology, it is physically set up in a star topology.
login
A noun used to refer to the login prompt, such as ‘At the login prompt, enter your username’.
look at
Do not use. Use ‘examine’ instead.
lookup
As a noun, correct.
As a verb, use "look up".
As a modifier, hyphenate. For example, "a look-up table".
loopback address
The loopback address is a special IP number (127.0.0.1) that is designated for the software loopback interface of a machine. The loopback interface has no hardware associated with it, and it is not physically connected to a network.
The loopback interface allows IT professionals to test IP software without worrying about broken or corrupted drivers or hardware.
lots of
Do not use. Use ‘many’ instead.
LPAR
Short for logical partitioning, a system of taking a computer’s total resources — processors, memory and storage — and splitting them into smaller units that each can be run with its own instance of the operating system and applications. Logical partitioning, which requires specialized hardware circuits, is typically used to separate different functions of a system, such as web serving, database functions, client/server actions or systems that serve multiple time zones and/or languages. Logical partitioning can also be used to keep testing environments separated from the production environments. Since the partitions in effect act as separate physical machines, they can communicate with each other. IBM was the first to use logical partitioning in 1976.
ls
When referring to the UNIX list command, use ls. For example, ’Type ls for the list of files in the directory’.

M

make sure
This means ‘be careful to remember, attend to, or find out something’. For example, ‘make sure the rhedk group is listed in the output’.
You may be able to use verify or ensure instead.
manual/man page
Correct. Two words. Do not use ‘manpage’.
matrixes
Correct. Do not use ‘matrices’.
may/can
Use ‘can’ to describe actions or conditions that are possible. Use ‘may’ only to describe situations where permission is being given. If either ‘can,’ ‘could,’ or "may’ apply, use ‘can’ because it’s less tentative.
MB
  • When spelled MB, short for megabyte (1,000,000 or 1,048,576 bytes, depending on the context).
  • When spelled Mb, short for megabit.
MBps
Short for megabytes per second, a measure of data transfer speed. Mass storage devices are generally measured in MBps.
MBR
Short for Master Boot Record, a small program that is executed when a computer boots up. Typically, the MBR resides on the first sector of the hard disk. The program begins the boot process by looking up the partition table to determine which partition to use for booting. It then transfers program control to the boot sector of that partition, which continues the boot process. In DOS and Windows systems, you can create the MBR with the FDISK /MBR command.
media
  • Objects on which data can be stored. These include hard disks, diskettes, CDs, and tapes.
  • In computer networks, media refers to the cables linking workstations together. There are many different types of transmission media, the most popular being twisted-pair wire (normal electrical wire), coaxial cable (the type of cable used for cable television), and fibre optic cable (cables made out of glass).
  • The form and technology used to communicate information. Multimedia presentations, for example, combine sound, pictures, and videos, all of which are different types of media.
menu-driven
Correct. Do not use "menu driven" or "menudriven".
Refers to programs whose user interface employs menus. The antithesis of a menu-driven program is a command-driven program.
metadata
Correct. Do not use "meta data" or "meta-data".
mount
  • To make a mass storage device available. In Linux environments, for example, inserting a floppy disk into the drive is called mounting the floppy.
  • To install a device, such as a disk drive or expansion board.
mouse button
Do not use ‘mouse-button’ or ‘mousebutton’. If you need to indicate which mouse button, put ‘right,’ ‘left,’ or ‘center’ at the beginning of the string, with no hyphen in between, such as ‘right mouse button’.
multiprocessing
Correct. Do not use ‘multi-processing’.
must
Use when referring to a task that is necessary for the user to do. For example, ’You must make a backup’ is a requirement, while ‘You should make a back-up’ is a suggestion.
Mutexes
Correct. "Mutex" is an abbreviation of "mutual exclusion". Consequently, "mutexes" is the correct plural form.

N

nameserver
Correct. Do not use ‘name server’.
namespace
Correct. Do not use ‘name space’ or ‘name-space’.
need
Use ‘need’ instead of ‘desire’ and ‘wish’. Use ‘want’ when the reader’s actions are optional (that is, they may not ‘need’ something but may still ‘want" something).
needs, needs to be, need to
Avoid when possible. Suggested alternatives include ‘must,’ ’required,’ or ‘should’.
neighbor
Correct. Do not use ‘neighbour’.
network
A group of two or more computer systems linked together.
network transparency
A condition in which an operating system or other service allows the user access to a remote resource through a network without needing to know if the resource is remote or local. For example, Sun Microsystems’ NFS, which has become a de facto industry standard, provides access to shared files through an interface called the Virtual File System (VFS) that runs on top of the TCP/IP stack. Users can manipulate shared files as if they were stored locally on the user’s own hard disk.
newer
Refer to later
NFS
Abbreviation of Network File System, a client/server application designed by Sun Microsystems that allows all network users to access shared files stored on computers of different types. NFS provides access to shared files through an interface called the Virtual File System (VFS) that runs in a layer above TCP/IP. Users can manipulate shared files as if they were stored locally on the user’s own hard disk.
With NFS, computers connected to a network operate as clients while accessing remote files, and as servers while providing remote users access to local shared files. The NFS standards are publicly available and widely used.
node
  • (1) In networks, a processing location. A node can be a computer or some other device, such as a printer. Every node has a unique network address, sometimes called a Data Link Control (DLC) address or Media Access Control (MAC) address.
  • (2) In tree structures, a point where two or more lines meet.
nonsecure
Do not use. Use ‘insecure’ instead.
NULL or null
When a command or value is stated, use NULL. When stating that something is null, use ‘null,’ all lowercase.
numbers
Spell out numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of…), and very large values, (4 billion). Use numerals for numbers 10 and greater, negative numbers, fractions, percentages, decimals, measurements, references to book sections (Chapter 3, Table 5, Page 11), and numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (You answered 8 out of 14 questions correctly). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions.
Do not use commas in numbers with four digits (use 1000 rather than 1,000). Do use commas in numbers with five or more digits (10,000; 123,456,789; 1,000,000,000).

O

object-oriented
Correct. Do not use ‘object oriented’ or ’objectoriented’. This is a modifier, such as ‘Java is an object-oriented language’.
Objective C
Correct. Do not use ‘Objective-C’.
OEM
  • (n) Stands for original equipment manufacturer, which is a misleading term for a company that has a special relationship with computer producers. OEMs buy computers in bulk and customize them for a particular application. They then sell the customized computer under their own name. The term is really a misnomer because OEMs are not the original manufacturers — they are the customizers.
  • (v) To provide equipment to another company, an OEM, which customizes and markets the equipment.
offline
Correct. Do not use ‘off-line’.
NB: as of November 2008, general usage in both US and Commonwealth English show ‘off-line’ is still the standard spelling. Our usage reflects the rule below regarding online vs on-line.
‘Offline’ is considered a legitimate alternative (as compared to an incorrect) spelling in several corpora, including WordNet and the OED. Given this it is reasonable to assume the hyphen will eventually disappear, putting our usage rule a little bit but not too far ahead of the current usage curve.
OK
When referring to the OK button, it is not necessary to use ‘button’ in the sentence; use ‘Click OK to close the dialog box’.
on-the-fly
Do not use. Avoid using idioms, as this saying is not globally known. Substitute ‘real time’ or similar instead.
online
Correct. Do not use ‘on-line’.
oops
Avoid if at all possible. If usage cannot be avoided, the correct term is "kernel Oops". Do not use "oops", "OOPS", or any other variation. The preferred term is always "kernel panic".
opcodes
Correct. Do not use ‘op-codes’.
open architecture
An architecture whose specifications are public. This includes officially approved standards as well as privately designed architectures whose specifications are made public by the designers. The opposite of open is closed or proprietary.
open source
Correct. Do not use ‘OpenSource,’ ‘opensource,’ or ’open-source’ (obviously, capitalize ‘open source’ at the beginning of a sentence).
operating system
Correct. Do not use Operating System, or OS.
orientate
Do not use. A user becomes ‘oriented’ to an environment. Try a synonym such as ‘familiarize,’ as in ‘This section helps familiarize you with the environment’.
output device
Any machine capable of representing information from a computer. This includes display screens, printers, plotters, and synthesizers.
override
Correct. Do not use "over-ride" or "over ride".

P

p.m.
Refer to a.m.
packet
A piece of a message transmitted over a packet-switching network. See under packet switching. One of the key features of a packet is that it contains the destination address in addition to the data. In IP networks, packets are often called datagrams.
packet-switching
Refers to protocols in which messages are divided into packets before they are sent. Each packet is then transmitted individually and can even follow different routes to its destination. Once all the packets forming a message arrive at the destination, they are recompiled into the original message.
Most modern Wide Area Network (WAN) protocols, including TCP/IP, X.25, and Frame Relay, are based on packet-switching technologies. In contrast, normal telephone service is based on a circuit-switching technology, in which a dedicated line is allocated for transmission between two parties. Circuit-switching is ideal when data must be transmitted quickly and must arrive in the same order in which it’s sent. This is the case with most real-time data, such as live audio and video. Packet switching is more efficient and robust for data that can withstand some delays in transmission, such as email messages and web pages.
A new technology, ATM, attempts to combine the best of both worlds — the guaranteed delivery of circuit-switched networks and the robustness and efficiency of packet-switching networks.
palmtop
Correct. Using PDA is preferred.
A small computer that literally fits in your palm. Compared to full-size computers, palmtops are severely limited, but they are practical for certain functions such as phone books and calendars. Palmtops that use a pen rather than a keyboard for input are often called hand-held computers or PDAs.
Because of their small size, most palmtop computers do not include disk drives. However, many contain PCMCIA slots in which you can insert disk drives, modems, memory, and other devices.
Palmtops are also called PDAs, hand-held computers and pocket computers.
pc or PC
When referring to program counter, use pc. The first instance must have the acronym defined, such as ‘program counter (pc)’.
When referring to a general computer, use ‘PC’.
PDA
Short for personal digital assistant, a handheld device that combines computing, telephone/fax, and networking features. A typical PDA can function as a cellular phone, fax sender, and personal organizer. Unlike portable computers, most PDAs began as pen-based, using a stylus rather than a keyboard for input. This means that they also incorporated handwriting recognition features. Some PDAs can also react to voice input by using voice recognition technologies.
PDAs of today are available in either a stylus or keyboard version.
PDAs are also called palmtops, hand-held computers and pocket computers.
peer-to-peer architecture
A type of network in which each workstation has equivalent capabilities and responsibilities. This differs from client/server architectures, in which some computers are dedicated to serving the others. Peer-to-peer networks are generally simpler, but they usually do not offer the same performance under heavy loads.
peripheral device
A computer device, such as a CD-ROM drive or printer, that is not part of the essential computer, for example, the memory and microprocessor. Peripheral devices can be external — such as a mouse, keyboard, printer, monitor, external Zip drive or scanner — or internal, such as a CD-ROM drive, CD-R drive or internal modem. Internal peripheral devices are often referred to as integrated peripherals. Also see I/O.
Pico
Capitalize when referring to the text editor or to the programming language. Do not capitalize when referring to the SI prefix.
plain text
Correct. Do not use ‘plaintext,’ ‘plain-text,’ or ‘clear text’.
platform
The underlying hardware or software for a system. For example, the platform might be an Intel 80486 processor running DOS Version 6.0. The platform could also be UNIX machines on an Ethernet network.
The platform defines a standard around which a system can be developed. Once the platform has been defined, software developers can produce appropriate software and managers can purchase appropriate hardware and applications. The term is often used as a synonym of operating system.
The term cross-platform refers to applications, formats, or devices that work on different platforms. For example, a cross-platform programming environment enables a programmer to develop programs for many platforms at once.
please
Do not use. Instead of saying ‘Please refer to the Getting Started Guide,’ use ‘Refer to the Getting Started Guide’.
plug-in
Correct. Do not use "plugin".
A hardware or software module that adds a specific feature or service to a larger system. For example, a number of plug-ins are available for the Netscape Navigator browser that enable it to display different types of audio or video messages. Navigator plug-ins are based on MIME file types.
pop-up
Correct. Do not use ‘popup’ or ‘Pop-up’.
POSIX
Correct. Do not use "Posix", "posix", or variations thereof.
An acronym for "Portable Operating System Interface for Unix".
PowerPC
Correct. Do not use ‘PPC’, ‘P-PC’ or variations thereof.
PPP
Correct. Do not use ‘ppp’ or ‘Ppp’.
press
Use for keyboard instructions. For example: ‘Press the Enter key’. For buttons, see click.
protocol
An agreed-upon format for transmitting data between two devices. The protocol determines the following:
  • the type of error checking to be used
  • data compression method, if any
  • how the sending device will indicate that it has finished sending a message
  • how the receiving device will indicate that it has received a message
There are a variety of standard protocols from which programmers can choose. Each has particular advantages and disadvantages; for example, some are simpler than others, some are more reliable, and some are faster.
From a user’s point of view, the only interesting aspect about protocols is that your computer or device must support the right ones if you want to communicate with other computers. The protocol can be implemented either in hardware or in software.
proxy server
A server that sits between a client application, such as a web browser, and a real server. It intercepts all requests to the real server to see if it can fulfill the requests itself. If not, it forwards the request to the real server.
Proxy servers have two main purposes:
  • Improve Performance: Proxy servers can dramatically improve performance for groups of users. This is because it saves the results of all requests for a certain amount of time. Consider the case where both user X and user Y access the World Wide web through a proxy server. First user X requests a certain web page, which we’ll call Page 1. Sometime later, user Y requests the same page. Instead of forwarding the request to the web server where Page 1 resides, which can be a time-consuming operation, the proxy server simply returns the Page 1 that it already fetched for user X. Since the proxy server is often on the same network as the user, this is a much faster operation. Real proxy servers support hundreds or thousands of users. The major online services such as Compuserve and America Online, for example, employ an array of proxy servers.
  • Filter Requests: Proxy servers can also be used to filter requests. For example, a company might use a proxy server to prevent its employees from accessing a specific set of websites.
pseudo-ops
Correct. Do not use ‘pseudo ops’ or ‘pseudoops’.
pulldown
Correct. Do not use ‘pull-down’.
PXE
Short for Pre-Boot Execution Environment. Pronounced ‘pixie,’ PXE is one of the components of Intel’s WfM specification. It allows a workstation to boot from a server on a network prior to booting the operating system on the local hard drive. A PXE-enabled workstation connects its NIC to the LAN via a jumper, which keeps the workstation connected to the network even when the power is off. Because a network administrator does not have to physically visit the specific workstation and manually boot it, operating systems and other software, such as diagnostic programs, can be loaded onto the device from a server over the network.
PXE is a mandatory element of the WfM specification. To be considered compliant, the PXE must be supported by the computer’s BIOS and its NIC.

Q

quiescent
Do not use. This is a lofty-sounding word that just means at rest; quiet; still; inactive or motionless.
With reference to a measurable property or system it can also mean not active. So, a system can be quiescent, meaning it is inactive, or (by extension) in a known, unchanging state.
If this is what you mean, this is what you should write.
If a system is, or needs to be inactive, write inactive. If a system is, or needs to be safe, write safe.

R

RAM
Correct. Do not use "Ram" or any other variations. This is an acronym for "random access memory".
RAM disk
Correct. Do not use "RAMdisk," "ramdisk," or "RAM-disk".
Refers to RAM that has been configured to simulate a disk drive. You can access files on a RAM disk as you would access files on a real disk. RAM disks, however, are approximately a thousand times faster than hard disk drives. They are particularly useful, therefore, for applications that require frequent disk accesses.
raw
Unprocessed. The term refers to data that is passed along to an I/O device without being interpreted. In contrast, cooked refers to data that is processed before being passed to the I/O device.
The term comes from UNIX, which supports cooked and raw modes for data output to a terminal. In cooked mode, special characters, such as erase and kill are processed by the device driver before being sent the output device.
raw data
Information that has not been organized, formatted, or analyzed.
read
  • (v) To copy data to a place where it can be used by a program. The term is commonly used to describe copying data from a storage medium, such as a disk, to main memory. Also used to refer to the act of determining the contents of a variable or parameter.
  • (n) The act of reading. For example, a fast disk drive performs 100 reads per second.
read-only
Capable of being displayed, but not modified or deleted. All operating systems allow you to protect objects (disks, files, directories) with a read-only attribute that prevents other users from modifying the object.
read/write
Capable of being displayed (read) and modified (written to). Most objects (disks, files, directories) are read/write, but operating systems also allow you to protect objects with a read-only attribute that prevents other users from modifying the object.
real time/real-time
Depends. If used as a noun, it is the actual time during which something takes place. For example, "The computer may partly analyze the data in real time (as it comes in) -- R. H. March". If used as an adjective, "real-time" is appropriate. For example, "XEmacs is a self-documenting, customizable, extensible, real-time display editor".
reboot
Correct. Do not use "re-boot".
refer to
Use to indicate a reference (within a manual) or a cross-reference (to another manual or documentation source).
remote access
The ability to log onto a network from a distant location. Generally, this implies a computer, a modem, and some remote access software to connect to the network. Whereas remote control refers to taking control of another computer, remote access means that the remote computer actually becomes a full-fledged host on the network. The remote access software dials in directly to the network server. The only difference between a remote host and workstations connected directly to the network is slower data transfer speeds.
remote access server
A server that is dedicated to handling users that are not on a LAN but need remote access to it. The remote access server allows users to gain access to files and print services on the LAN from a remote location. For example, a user who dials into a network from home using an analog modem or an ISDN connection will dial into a remote access server. Once the user is authenticated they can access shared drives and printers as if they were physically connected to the office LAN.
required
See must.
return
When referring to the keyboard key on Solaris or Mac, use Returnor return, respectively. See enter for other platforms.
right now
Use "now" instead.
right-click
Correct. Do not use "right click".
ROM
Acronym for read-only memory, computer memory on which data has been prerecorded. Once data has been written onto a ROM chip, it cannot be removed and can only be read.
Unlike main memory (RAM), ROM retains its contents even when the computer is turned off. ROM is referred to as being nonvolatile, whereas RAM is volatile.
Most personal computers contain a small amount of ROM that stores critical programs such as the program that boots the computer. In addition, ROMs are used extensively in calculators and peripheral devices such as laser printers, whose fonts are often stored in ROMs.
A variation of a ROM is a PROM (programmable read-only memory). PROMs are manufactured as blank chips on which data can be written with a special device called a PROM programmer.
RPM
Initialism for the RPM Package Manager. RPM manages files in the RPM format, known as RPM packages, which can be installed with the ‘rpm’ command.
runlevel
Correct. Do not use "run level" or "run-level".
runtime
Correct. Do not use "run time" or "run-time".

S

S-record
Correct. Do not use ‘s-record’, ‘S-Record’, ’s-Record’, or any other variations.
Samba
Correct. Do not use ‘samba’ or ‘SAMBA’.
screen saver
Correct. Do not use ‘screensaver’.
screenshot
Correct. Do not use ‘screen shot’.
scrollbar
Correct. Do not use ‘scroll bar’ or ‘scroll-bar’.
see
Do not use if referring readers to another resource. Use "refer to" instead.
select
Use when referring to menu options. For example, ‘From the File menu, select Save’.
SELinux
Short for Security-Enhanced Linux, SELinux uses Linux Security Modules (LSM) in the Linux kernel to provide a range of minimum-privilege-required security policies. SELinux is, by dint of community use if not by formal declaration, the standard short-hand expression for delineating the project, its implementation and its effect (for both good and ill, at least from the user’s point of view). Alternatives, such as ‘SE-Linux’, ‘S-E Linux’ and ‘SE Linux’ should not be used.
semicolon
Correct. Do not use ‘semi-colon’.
sends out
Do not use. Instead, use ‘emits’ or ‘issues’.
server farm
Also referred to as server cluster, computer farm or ranch. A server farm is a group of networked servers that are housed in one location. A server farm streamlines internal processes by distributing the workload between the individual components of the farm and expedites computing processes by harnessing the power of multiple servers. The farms rely on load-balancing software that accomplishes such tasks as tracking demand for processing power from different machines, prioritizing the tasks and scheduling and rescheduling them depending on priority and demand that users put on the network. When one server in the farm fails, another can step in as a backup.
Combining servers and processing power into a single entity has been relatively common for many years in research and academic institutions. Today, more and more companies are utilizing server farms as a way of handling the enormous amount of computerization of tasks and services that they require.
A web server farm, or web farm, refers to either a web site that runs off of more than one server or an ISP that provides web hosting services using multiple servers.
server-side/server side
Careful here. For example: SMB is a server-side service used to provide file sharing to Windows clients. SMB runs on the server side of a client/server Samba implementation. See client-side/client side.
setup/set up
"Setup’ is a noun. ‘Set up’ is a verb.
shadow passwords
Not a proper noun, so capitalize ‘Shadow’ at the beginning of a sentence only.
Shadow passwords are a method of improving system security by moving the encrypted passwords (normally found in /etc/passwd) to /etc/shadow, which is readable only by root. This option is available during installation and is part of the shadow utilities package.
shadow utilities
Not a proper noun, so capitalize ‘Shadow’ at the beginning of a sentence only.
share name
Correct. Do not use "sharename" or "Sharename" unless you are quoting the output of commands, such as "smbclient -L".
shell
A "shell" is a software application, for example, /bin/bash or /bin/sh, that provides an interface to a computer. Do not use this term to describe where to type commands. Use ‘shell prompt’ instead.
shell prompt
Correct. Refers to the character at the beginning of the command line, and indicates that the shell is ready to accept commands. Do not use ‘command prompt,’ ‘terminal,’ or ‘shell’..
should
Do not use if it is something the user must do. For example, ’You should make a backup’ is a suggestion, while ’You must make a backup’ is a requirement.
shut down
Correct. Do not use "shut-down". Only use "shutdown" when referring to the system command, /sbin/shutdown.
simply
Do not use. See basically.
since or because
Do not use "since" to mean "because", it is ambiguous. Use "because" to refer to a reason. Use "since" to refer to the passage of time.
smart card
Correct. Do not use smartcard or smart-card.
snippet
Do not use snippet or tidbit to refer to short or small sections of information. Use "piece" instead. Use "excerpt" to refer to samples taken from a more extensive section of text.
SOCKS
Correct. Do not use "socks". When specifying a SOCKS version, use "SOCKSv4" or "SOCKSv5".
softcopy
Do not use. Instead, use ‘online’. For example, ‘To view the online documentation…’.
sound card
Correct. Do not use ‘soundcard’ or ‘sound-card’.
space
Use when referring to white space, such as ‘Ensure there is a space between each command’. Use ‘Spacebar’ when referring to the keyboard key.
Spacebar
Use when referring to the keyboard key, such as ‘Press the Spacebar key to continue’.
spec file
Correct. When referring to the RPM spec file, do not use ‘specfile’.
specific
When used as a modifier, put a hyphen before specific, such as "MIPS-specific", "Linux-specific", and "chip-specific".
spelt
Incorrect. Use "spelled" instead.
"Spelt" is the standard spelling in Commonwealth English but US English prefers "spelled", although "spelt" is occasionally seen in US English.
SSH
Short for Secure Shell, a network protocol that allows data exchange using a secure channel. Do not use "ssh", "Ssh", or other variants.
SSL
Short for Secure Sockets Layer, a protocol developed by Netscape for transmitting private documents via the Internet. SSL works by using a public key to encrypt data that’s transferred over the SSL connection. Both Netscape
Navigator and Internet Explorer support SSL, and many websites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https: instead of http:.
standalone
Correct. Do not use "stand alone" or "stand-alone".
Refers to a device that is self-contained, one that does not require any other devices to function. For example, a fax machine is a standalone device because it does not require a computer, printer, modem, or other device. A printer, on the other hand, is not a standalone device because it requires a computer to feed it data.
starts up
Do not use. Instead, use ‘activates’ or ‘invokes’.
startx
Correct. Do not use StartX or other variants.
su
Correct. Do not use SU (all caps).
subdirectory
Correct. Do not use sub-directory.
submenu
Correct. Do not use ‘sub-menu’.
superuser
A synonym for root. More common in Solaris documentation than Linux. If and when used, this is the correct spelling. Do not use ‘super user’ or ‘super-user’.
swap space
Correct. Do not use ‘swapspace’. If starting the beginning of a sentence, ‘Swap space’ is allowed.
symmetric encryption
A type of encryption where the same key is used to encrypt and decrypt the message. This differs from asymmetric (or public-key) encryption, which uses one key to encrypt a message and another to decrypt the message.

T

tar
Correct. ‘gtar’, ’guntar’, and ‘untar’ are also acceptable. Do not use ‘TAR’.
taskbar
Correct. Do not use ‘task bar’.
TCP
Abbreviation of Transmission Control Protocol, and pronounced as separate letters. TCP is one of the main protocols used for the transport (layer 4 in the OSI model) in modern networks (the other major protocol is UDP). IP (layer
3 by the OSI model) is the protocol which deals only with packets, TCP allows two hosts to establish a two way connection and exchange streams of data. TCP guarantees delivery of data and sorts packets so they appear to be delivered in the same order in which they were sent.
TCP/IP
Abbreviation for Transmission Control Protocol/Internet Protocol, the suite of communications protocols used to connect hosts on the Internet. TCP/IP uses several protocols, the two main ones being TCP and IP. TCP/IP is built into the UNIX operating system and is used by the Internet, making it the de facto standard for transmitting data over networks. Even network operating systems that have their own protocols, such as Netware, also support TCP/IP.
telephone numbers
Use spaces, not dashes or dots, to punctuate phone numbers. When indicating a number for international use, include the country code (+1 555 555 5555 for a US number, for example). US 800 numbers are not accessible from outside the country, so do not precede them with a country code (800 555 5555). Phone numbers beginning with 0 are not for international use. Make these numbers ready for international by dropping the zero and adding the appropriate country code. For example, (055) 12345 would be for use in Italy only; change it to +39 (55) 12345 for international use.
Telnet
Telnet is always capitalized. It is a terminal emulation program for TCP/IP networks.
terminal
Do not use to describe where to type commands. Use ‘command line’ instead.
  • A device that enables you to communicate with a computer. Generally, a terminal is a combination of keyboard and display screen.
  • This can be an XTerm, a GNOME Terminal, KDE‘s Konsole, or another such terminal application that offers the use of a shell prompt within the GUI environment.
  • In networking, a terminal is a personal computer or workstation connected to a mainframe. The personal computer usually runs terminal emulation software that makes the mainframe think it is like any other mainframe terminal.
terminal emulation
Refers to making a computer respond like a particular type of terminal. Terminal emulation programs allow you to access a mainframe computer or bulletin board service with a personal computer.
terminal window
Do not use to describe where to type commands. Use ‘shell prompt’ instead.
terminate
If a Windows procedure is being terminated, use ‘terminate’. For example ‘To terminate the procedure, press the Q key’. See kill for UNIX commands.
text mode
Correct. Do not use ‘textmode’ or ‘text-mode’.
A video mode in which a display screen is divided into rows and columns of boxes. Each box can contain one character. Text mode is also called character mode.
All video standards for the PC, including VGA, support a text mode that divides the screen into 25 rows and 80 columns. In addition to text mode, most video adapters support a graphics mode, in which the display screen is divided into an array of pixels.
Whereas character-based programs run in text mode, all graphics-based programs run in graphics mode.
text-based
Correct. Do not use ‘text based’.
that/which
‘That’ introduces a restrictive clause — a clause that must be there for the sentence to make sense. A restrictive clause often defines the noun or phrase preceding it.
‘Which’ introduces a non-restrictive, parenthetical clause — a clause that could be omitted without affecting the meaning of the sentence.
For example: The car was travelling at a speed that would endanger lives. The car, which was travelling at a speed that would endanger lives, swerved onto the sidewalk.
Use ‘who’ or ‘whom,’ rather than ‘that’ or ‘which,’ when referring to a person.
then/than
‘Then’ refers to a time in the past or the next step in a sequence. ‘Than’ is used for comparisons.
third-party
Correct. Do not use ‘third party’.
this
The word ‘this’ can be used as an adjective or a pronoun. If you use it as a pronoun, be clear what the antecedent is. If it is unclear, use the adjective form by following ‘this’ with a noun.
this is a feature, not a bug
Do not use. Instead, explain why and where the operation is useful, and where the operation may cause unwanted results.
three-tier
A special type of client/server architecture consisting of three well-defined and separate processes, each running on a different platform:
  • The user interface, which runs on the user’s computer (the client).
  • The functional modules that actually process data. This middle tier runs on a server and is often called the application server.
  • A database management system (DBMS) that stores the data required by the middle tier. This tier runs on a second server called the database server.
The three-tier design has many advantages over traditional two-tier or single-tier designs, the chief ones being:
  • The added modularity makes it easier to modify or replace one tier without affecting the other tiers.
  • Separating the application functions from the database functions makes it easier to implement load balancing.
through
Correct. Do not use ‘thru’ and do not use the hyphen (-), em-dash (—), en-dash (–) or any other dash.
throughput
The amount of data transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughputs are measured in kbps, Mbps and Gbps.
time zone
Correct. Do not use ‘timezone’ or ‘time-zone’.
timeout
Correct. Do not use ‘time out’ or ‘time-out’.
token
  • In programming languages, a single element of a programming language. For example, a token could be a keyword, an operator, or a punctuation mark.
  • In networking, a token is a special series of bits that travels around a token-ring network. As the token circulates, computers attached to the network can capture it. The token acts like a ticket, enabling its owner to send a message across the network. There is only one token for each network, so there is no possibility that two computers will attempt to transmit messages at the same time.
  • In security systems, a small device the size of a credit card that displays a constantly changing ID code. A user first enters a password and then the card displays an ID that can be used to log into a network. Typically, the IDs change every 5 minutes or so.
token-ring
  • A type of computer network in which all the computers are arranged (schematically) in a circle. A token, which is a special bit pattern, travels around the circle. To send a message, a computer catches the token, attaches a message to it, and then lets it continue to travel around the network.
  • When capitalized, Token Ring refers to the PC network architecture developed by IBM. The IBM Token-Ring specification has been standardized by the IEEE as the IEEE 802.5 standard.
toolbar
Correct. Do not use ‘tool bar’ or ‘tool-bar’.
totally
Do not use. See basically.
traffic
The load on a communications device or system. One of the principal jobs of a system administrator is to monitor traffic levels and take appropriate actions when traffic becomes heavy.
troubleshoot
Correct. Do not use ‘trouble shoot’ or ‘trouble-shoot’.
To isolate the source of a problem and fix it. In the case of computer systems, the term troubleshoot is usually used when the problem is suspected to be hardware -related. If the problem is known to be in software, the term debug is more commonly used.
truly
Do not use. See basically.
try and
Do not use. Use "try to" instead.
two-tier
Refers to client/server architectures in which the user interface runs on the client and the database is stored on the server. The actual application logic can run on either the client or the server. A newer client/server architecture, called a three-tier architecture introduces a middle tier for the application logic.
type
Type can be used as either a verb or noun. You can say ‘Print the data type of init’ or ‘To start Source-Navigator, type snavigator’.
Sometimes multi-field dialog boxes do not allow the user to press Enter to move between fields. In these cases, you need to state ‘press Enter’ at the end of the sentence, such as ‘Type in the name, address, town, and then press Enter’. See enter for information on single-field dialog boxes.

U

UID
UID and User ID are abbreviations of user identifier. Do not use "uid".
Unset
Incorrect. Use "Clear" instead.
To disable the Wobbly Widget, clear the Enable Wobbly Widget check box.
This rule only matches TCP packets that have the SYN flag set and the ACK flag cleared.
upgrade
Correct. Do not use "up-grade" or "up grade".
UPS
Abbreviation of uninterruptable power supply, a power supply that includes a battery to maintain power in the event of a power outage.
URLs
Include http, ftp, or https at the beginning of URLs. Use http://www.redhat.com rather than www.redhat.com.
usable
Correct. Do not use useable.
user
When referring to the reader, use "you" instead of "user". For example, "The user must..." is incorrect. Use "You must..." instead.
If referring to more than one user, calling the collection "users" is acceptable, such as "Other users may wish to access your database".
user interface
Correct. Do not use ‘user-interface’ or ‘userinterface’.
The junction between a user and a computer program. An interface is a set of commands or menus through which a user communicates with a program. A command-driven interface is one in which you enter commands. A menu-driven interface is one in which you select command choices from various menus displayed on the screen.
user space
Correct when used as a noun. When used as a modifier, use the hyphenated form, "user-space". Do not use "userspace".
userid
Acceptable abbreviation of user identifier.
username
Correct. Do not use ‘user name’.
utilize
Avoid this term. Write "use" instead.

V

VAR
Acronym for value-added reseller. Same as OEM (original equipment manufacturer).
verify
This means ‘to establish truth, accuracy, or reality’. For example, ‘Verify that the NFS server is responding before continuing’.
You may be able to use make sure or ensure instead.
vi
Correct; use all lower-case letters. Do not use ‘VI’ (all caps).
via
"...In its use as a preposition meaning 'by way of' or 'passing through' it is the Latin ablative...Via can only be properly used of the route; to apply it to the means of transport is a vulgarism. The luggage is being sent via London, but not The luggage is being sent via rail; and still less May I send a message via you?" (Sir Ernest Gowers, Fowler's Second Edition, Revised)
In the second example above, replace "via" with "by": The luggage is being sent by rail
This applies equally to transport protocols, such as TCP. You cannot send data "via" TCP.
The CPU and chipset manufacturer is VIA, not via.
video mode
Correct. Do not use ‘video-mode’ or ‘videomode’.
The setting of a video adapter. Most video adapters can run in either text mode or graphics mode. In text mode, a monitor can display only ASCII characters. In graphics mode, a monitor can display any bit-mapped image. In addition to the text and graphics modes, video adapters offer different modes of resolution and color depth.
Vim
Correct; Do not use ‘VIM’ (all caps) or ‘vim’ (all lowercase).
Vim is an acronym, derived from Vi IMproved. (In the original 1991 release for the Amiga platform, the acronym was derived from Vi IMitation. It became Vi IMproved when ported to various UNIX-based operating systems in 1992.) Despite being an acronym, and despite the first word of the ‘About’ text that appears when you launch the editor, the standard, Proper Noun-derived, mixed-case spelling has been in use since its release on the Amiga.
virtual console
Correct. Do not use ‘virtual-console’ or ‘Virtual Console’ for general use.
This can be abbreviated to ‘VC’ as long as the term has been introduced in that same content in its full version first, such as ‘A virtual console (also known as a VC) is a shell prompt in a non-graphical environment. Multiple VCs can be accessed simultaneously.’
virtual router
An abstract object managed by VRRP that acts as a default router for hosts on a shared LAN. It consists of a Virtual Router Identifier and a set of associated IP addresses across a common LAN.
VPN
Short for virtual private network, a network that is constructed by using public wires to connect nodes. For example, there are a number of systems that enable you to create networks using the Internet as the medium for transporting data. These systems use encryption and other security mechanisms to ensure that only authorized users can access the network and that the data cannot be intercepted.

W

WAN
A computer network that spans a relatively large geographical area. Typically, a WAN consists of two or more local-area networks (LANs).
Computers connected to a wide-area network are often connected through public networks, such as the telephone system. They can also be connected through leased lines or satellites. The largest WAN in existence is the Internet.
want
Correct. Use in preference to ‘wish’ or ‘would like’, or rewrite. For example, ‘If you want to use the debugger…’ could be rewritten much more simply as "To use the debugger..."
WCA
An abbreviation of "web clipping application", an application that allows users to extract static information from a web server and load that data onto a web-enabled PDA.
WCAs are also called "query applications".
we suggest
Do not use. Use a more direct construction, or use "recommend". For example, instead of "We suggest that you make a backup of your data disk", write "Back up your data disk", or "It is recommended that you back up your data disk."
web
Correct. Lowercase. Use this to describe the transmission of web pages on the internet. We are ahead of the curve of usage with our use of the common noun form instead of the proper noun form, ‘Web’.
This term should only be used when discussing HTTP interactions. When referring to all Internet services (mail, web traffic, ftp, etc) use Internet.
Web servers using the HTTP protocol to serve web sites, use web. The result of this interaction is the web. The web is a service on the Internet. Use web to refer to HTTP traffic.
web page
Correct. Use this in preference to the single-word alternative spelling: webpage.
web server
Correct. Do not use ‘webserver’. For example, ‘The Apache HTTP Server is the default web server…’.
website
This is now preferred to the older, two-word presentation: ‘web site’.
Unlike ‘web page’ vs ‘webpage’ (where the accepted standard spelling prefers the two-word version), this term has made the transition to a single-word form.
which/that
See that/which.
white space
Correct. Do not use ‘whitespace’ or ‘white-space’. White space refers to areas of the page with nothing on them. This space is not necessarily colored white.
Appropriate use of white space enhances page layout and make information easier to find and understand.
who/whom
Use the pronoun ‘who’ as a subject. Use the pronoun ‘whom’ as a direct object, an indirect object, or the object of a preposition.
For example: Who owns this? To whom does this belong?
wildcard
Correct. Do not use "wild-card", "wild card", or other variations.
will
Do not use future tense unless it is absolutely necessary. For example, do not write ‘The next section will describe the process in detail’. Instead, write ‘The next section describes the process in detail’.
Window Maker
Correct. Do not combine into one word or hyphenate. This is a window manager for the X Window System.
wish
Use ‘need’ instead of ‘desire’ and ‘wish’. Use ‘want’ when the reader’s actions are optional (that is, they may not ‘need’ something but may still ‘want’ something).
workstation
A type of computer used for engineering applications (CAD/CAM), desktop publishing, software development, and other types of applications that require a moderate amount of computing power and relatively high quality graphics capabilities.
In networking, workstation refers to any computer connected to a local-area network. It could be a workstation or a personal computer.
World Wide Web
Correct. Capitalize each word. Abbreviate as ‘WWW’ or ‘web’. Note that this term is becoming archaic; use Internet or web.
writable
Correct. Do not use writeable.
write
To copy data from main memory to a storage device, such as a disk.

X

X
An alternative reference to the X Window System. Do not use X by itself when referring to XEmacs.
X Window System
Also referred to as X. When making multiple references to the X Window System, the complete reference must appear first, with shortened references following. For example, "Reinstalling the X Window System, or X, is not necessary if... To start an X session, from the shell prompt...".
X Windows
Do not use. This is an incorrect reference to the X Window System (or X).
x86
Correct. Do not capitalize the ‘x’.
XEmacs
Correct. Do not use ‘Xemacs’. Use ‘xemacs’ only when referring to a command, such as ‘To start XEmacs, type xemacs’.
xterm
Correct. Do not use ‘Xterm’ unless the word is used at the beginning of a sentence.

Y

you
Correct. Do not use ‘I’, ‘he’, or ‘she’.
you may
Avoid using this. For example, "you may" can be eliminated from the following: "You may double-click the desktop..."

Chapter 2. Punctuation

2.1. Colons and semicolons
2.1.1. To relate clauses
2.1.2. To introduce a series or list
2.2. Commas
2.2.1. In compound sentences
2.2.2. In adverbial clauses and phrases
2.2.3. In adjectival clauses and phrases
2.2.4. With coordinate adjectives
2.2.5. With series and lists
2.3. Parentheses
2.4. Quotation Marks
2.5. Apostrophes

2.1. Colons and semicolons

2.1.1. To relate clauses

Current standards allow the use of a colon or semicolon in the following sentences. The sentences show a connection or shared theme between two clauses, or use the second clause to reiterate or amplify the idea in the first clause:
  • They had been writing code all night: this could explain their bloodshot eyes.
  • They had been writing code all night; this could explain their bloodshot eyes.
  • I spend a lot of money on food; last month, I went out to eat 36 times.
  • I spend a lot of money on food: last month, I went out to eat 36 times.
Remember to start the phrase following a colon or semicolon with a lowercase letter.
Try to limit your use of colons and semicolons. Separate sentences with a period if possible.

2.1.2. To introduce a series or list

A colon is generally used before a list or series:
  • The Triangle Area consists of three cities: Raleigh, Durham, and Chapel Hill.
But not if the list is a complement or object of an element in the sentence:
  • Before going on vacation, be sure to (1) set the alarm, (2) cancel the newspaper, and (3) ask a neighbor to collect your mail.
  • The colors I hate most are:
    • green
    • orange
    • pink
    • magenta
Use a colon after "as follows" and "the following" if the related list comes immediately after:
  • The steps for changing directories are as follows:
    1. Open a terminal.
    2. Type cd...
Use a colon to introduce a bullet list (or dash, or icon/symbol of your choice):
  • In the Properties dialog box, you'll find the following entries:
    • Connection name
    • Count
    • Confirm starting connection
    • Confirm stopping connection
    • Cost per
Use a semicolon to separate items in a series if the items contain commas:
  • Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner.
Use a semicolon before a conjunctive adverb (however, therefore, otherwise, namely, for example, etc.):
  • I think; therefore, I am.

2.2. Commas

2.2.1. In compound sentences

Use a comma to join clauses in a compound sentence, unless the clauses are short and have a similar theme:
  • I spent five hours working on this document, but I lost it when my computer crashed.
  • Do you want to go the mall and the grocery store with me, or are you going to watch football instead?
  • You wash and I'll dry.
A comma can be omitted from a sentence with several clauses, but only when there's little chance that the sentence could be misread without it:
  • We played football all afternoon and were completely exhausted but we still stayed up watching movies all night.
That sentence is fine, but adding a comma before "...but we still stayed up..." would provide a pause and avoid the chance of having it read like a run-on sentence.
In a compound sentence containing several short independent clauses, separate the clauses with commas AND USE A COMMA BEFORE THE CONJUNCTION:
  • You need to go to the grocery store for milk, drop off my dry cleaning, and pick up your little sister from soccer practice.

2.2.2. In adverbial clauses and phrases

If a dependent clause is restrictive (omission will affect the meaning of the main clause), don't set it off with commas. If it is nonrestrictive (omission will not affect the main clause), set it off with commas:
  • I'll go to lunch with you if we can get pizza.
  • I don't want to go out for pizza, because I had pizza yesterday.
If a dependent clause comes BEFORE the main clause, use a comma whether the clause is restrictive or not:
  • If we get pizza, I'll go to lunch with you.
  • When I heard the voice on the other end of the line, I was quite surprised.

2.2.3. In adjectival clauses and phrases

An adjective clause that can be dropped without changing the meaning of the sentence is set off with commas:
  • The application, which comes with excellent documentation, is used by many graphic artists.
An adjective clause that cannot be dropped without changing the meaning of the sentence is not set off with commas:
  • The plan that matters most to us will be easy to implement.

2.2.4. With coordinate adjectives

Separate coordinate adjectives (two or more adjectives modifying the same noun) with commas:
  • My dog is loyal, obedient, and affectionate.
  • It was a long, boring meeting.

2.2.5. With series and lists

Separate elements in a series of three or more with commas, including a comma before the conjunction if one is used:
  • Today I am wearing socks, shoes, pants, and a shirt.

2.3. Parentheses

Parentheses are similar to commas in that they set off information that further explains or enhances a statement. Information that is very closely related to the statement should be set off with commas; information that is more incidental should be set off with parentheses.
  • I tried to get to the elevator before the door shut, but I was too slow.
  • Most of my favorite authors (Shakespeare, Dickens, Woolf) are dead.
Expressions beginning with i.e., e.g., that is and so on can be set off with parentheses if they cause a major break in the sentence. If the break is minor, use commas.
  • He interviewed the biggest stars of the day, namely, Madonna, Michael Jackson, and Jack Nicholson.
  • Classic works of literature (e.g.,Dickens, Shakespeare, the Brontes) lined the shelves.
If the contents of the parentheses include at least one complete sentence, the period goes inside the parentheses. If not, the period goes outside.

2.4. Quotation Marks

Commas and periods go inside quotation marks.
Question marks, exclamation points, dashes, and semicolons go inside the quotation marks IF they are part of the quote; if not, they go outside.
Don't put quotation marks around cliches or slang terms (in fact, just avoid using cliches and slang as it makes the translation of content more difficult).
A word or words being introduced to readers should not be placed in quotation marks (for our purposes, we use the SGML firstterm tag) for first reference. If you are writing outside of the SGML tagging enviroment, use quotation marks for first references. Subsequent references do not need quotation marks or the firstterm SGML tag.

2.5. Apostrophes

Plural nouns not ending in s should have add an 's (for example, the alumni's contribution).
Plural nouns ending in s only need an apostrophe (for example, the horses' food).
Singular common nouns ending in s should add an 's unless the next word begins with an s (for example, the witness's answer or the witness' story).
Singluar proper names ending in s only need an apostrophe (for example, Dickens' novels).

Chapter 3. Grammar

3.1. Active Voice
3.2. Agreement
3.2.1. Pronoun-Antecedent Agreement
3.3. Sentence Structure
3.3.1. Sentence Fragments
3.3.2. Run on sentences
3.4. Contractions
3.5. Gender References
3.6. Tense

3.1. Active Voice

Use the active voice ("Start Linuxconf by typing...") rather than passive ("Linuxconf can be started by typing...") whenever possible. Active voice makes for more lively, interesting reading.

3.2. Agreement

In grammar, agreement occurs when specific parts of a sentence are coordinated: that is, they "shake hands" in number or gender.
There are two forms of agreement: subject-verb agreement and pronoun-antecedent agreement. Subject-verb agreement is pretty rudimentary, so it won't be discussed here. Pronoun-antecedent agreement can be a little more problematic, so...

3.2.1. Pronoun-Antecedent Agreement

A pronoun is a word that is used in place of a noun (for example, I, he, she, it). An antecedent is a word or a phrase to which the pronoun refers.
Once you're comfortable with subject-verb agreement, pronoun- antecedent agreement often follows as a matter of course.
Here is an annotated roundup of pronoun-antecedent rules:
Singular and singular/plural and plural
Rule: A singular pronoun refers to a singular antecedent; a plural pronoun refers to a plural antecedent.
Examples:
  • The CD spins in its caddy. (Singular third-person pronoun its refers to the singular antecedent CD.)
  • The developers checked their work. (Plural third person pronoun their refers to the plural antecedent developers.)
Collective nouns
Rule: When collective nouns are used as antecedents, use singular to plural pronouns, depending on the sentence's meaning.
Examples:
  • Microsoft seems second to none in its marketing skills (Collective noun "Microsoft" takes a singular pronoun its because the collective noun refers to the group as a whole).
  • The developers were asked for their preferences (Collective noun "developers" takes the plural pronoun their because the reference is to the individuals of the group).
Who/whom/that/which
Use "whom," "who," or "that" to introduce a qualifying phrase when the antecedent is a person. Use "which" when referring to a thing. Use "which" or "that" to introduce a qualifying phrase when the antecedent is a concept or an object. Who, whom, that, and which are known as "relative pronouns."
Use the following as guidelines:
  • Who = relative pronoun when a person (or persons)is the subject
  • Whom = relative pronoun when person is not the subject
  • Which = relative pronoun for things
  • That = kind of a wildcard; can replace which or who
Examples:
  • The jewel case, which once held the CD, was broken recently.
  • The CD that I got for my birthday is defective.
  • Edward C. Bailey, who wrote "Maximum RPM,"...
  • The company which published "Maximum RPM" was...
  • He is the writer whose work includes "Maximum RPM."
  • This book belongs to whomever purchased it last week.
  • Who ate all the cereal?
  • To whom should I address the letter?
  • The desktop that was designed by Earl is not called GNOME.
  • The GNOME developers who worked on the desktop are...
  • The GNOME developers to whom I owe my gratitude are...

Quick tip

To help you choose between who and whom, substitute the person about whom (sorry, couldn't help it) you're talking with either him or he.
  • If your restatement would contain him, her, them, me, or us, you'll use whom and whomever. "I'm giving the book to him." "To whom am I giving the book?"
  • If the restatement would contain the word he, she, they, I, or we, you'll use who and whoever. "Do you think he would mind?" "Who do you think would mind?" "She's walking in the door." "Who's walking in the door?"

3.3. Sentence Structure

A sentence is one, complete thought. A sentence expresses something about a subject (a person, place, or thing) and a verb (what the subject is or does).
There are two common problems that occur in sentence construction: Sentence fragments and run-on sentences.

3.3.1. Sentence Fragments

A sentence fragment is a sentence which cannot stand by itself -- that is, it's out of context with the surrounding sentences.
Examples:
  • "We will release no upgrade before its time." Full, complete sentence.
  • "We will release no upgrade. At least, before its time." Two sentences, and the second sentence is a fragment, because if it's isolated it can't stand on its own.
Try this exercise: Read your sentences aloud, as if each sentence were the *only* sentence on a piece of paper. If you hear a sentence which wouldn't make any sense all by itself, chances are you've got a sentence fragment.
You can choose to repair the sentence by making it a complete thought, or you can choose to adjust it to work as a "stylistic fragment."
Stylistic fragments
When you choose to maintain a sentence fragment for the sake of variety in your work, you're deciding to use a stylistic fragment.
Deliberately inserting a sentence fragment for the sake of style can add color to the work, and help the reader by providing a break in the tone. That's good.
Be careful: Stylistic fragments can easily become a crutch (Too much of a good thing is not a good thing).

3.3.2. Run on sentences

Two or more complete ideas that are joined without punctuation create a run-on sentence (also called a fused sentence). The sentence doesn't have to be long to be a run-on -- although the longer your sentence, the more difficult it is to read.
You can:
  • Separate independent clauses with a period. Doing so will form two sentences out of one.
  • Use semicolons to form a compound sentence. Think of a semi-colon as an extended breather -- longer than a comma.
  • Insert a coordinating conjunction, such as "and" or "but" between the independent clauses, which will also form a compound sentence (Rosa Parks was a brave person, but her valor took conviction to stir a nation).
  • Insert a subordinating conjunction, which will create a subordinate clause in your sentence and create a compound sentence (Although Rosa Parks was a brave person, her valor took conviction to stir a nation).
Examples:
  • Run-on -- The CDs both of which belonged to the developers were in the test lab.
  • Correct -- The CDs, both of which belonged to the developers, were in the test lab.
  • Run-on -- The CDs, both of which belonged to the developers, were in the test lab, and because they were the only available CDs for the new release, the developers were anxious about keeping them clean.
  • Correct -- The CDs, both of which belonged to the developers, were in the test lab. Because they were the only available CDs for the new release, the developers were anxious about keeping them clean (Actually, the previous run-on sentence was technically correct because of the punctuation; however, it could have been broken to help readability).

3.4. Contractions

Do not use contractions in formal documentation.

3.5. Gender References

Do not use gender-specific pronouns in documentation. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers." It is fine to use "you" when giving instructions and "the user," "new users," etc. in more general explanations. Never use "one" in place of "you" when writing technical documentation. Using "one" is far too formal.

3.6. Tense

Avoid future tense (or using the term "will") whenever possible For example, future tense ("The screen will display...") does not read as well as the present tense ("The screen displays"). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system.

Chapter 4. Design

4.1. Heading Styles
4.2. Screenshots
4.3. Diagrams
4.4. Example Domain References
4.5. Example Computer Output
4.6. Admonitions
4.7. Additional Resources
4.8. Book References

4.1. Heading Styles

[discussion of title case goes here]

4.2. Screenshots

[guide to screenshots]

4.3. Diagrams

[guide to drawing diagrams]

4.4. Example Domain References

If you are showing an example that involves domain names, use the reserved top level DNS names: example.com, example.org, or example.net.
For details, read RFC 2606.

4.5. Example Computer Output

When showing example computer output (usually in screen tags), do you include the prompt or command (unless the command or prompt is the actually computer output you want to show).

4.6. Admonitions

To bring a statement to the reader's attention, use an admonition. The admonitions available are note, tip, important, warning, and caution.
When using an adminition, always include a title according to the type of adminition it is: Note, Tip, Warning, Important, or Caution. Do not use a phrase or anything else for the title.
Try to keep the statements as brief and to the point as possible.
Try to use adminitions sparingly so that they do not lose their effectiveness.
Use Note to bring additional information to the users' attention.
Use Tip to show the user helpful information or another way to perform a task.
Use Important to show the user a piece of information that should not be overlooked. While this information may not change anything the user is doing, it should show the user that this piece of information could be vital.
Use Warning to show the reader that his current setup will change or be altered, such as files being removed, and he should not choose this operation unless he is alright with the consequences.
Use Caution to show the user that he must be careful when attempting a certain step.
Refer to Quick Reference for SGML Commands for details on how to implement these in SGML.

4.7. Additional Resources

The Additional Resources section should be a sect1 and should be the last section in the chapter. Use the following style and titles, including sect2 titles. Each sect2 should contain an itemized list, and they should be listed in the following order: Installed Documentation, Useful Websites, Related Books.
The following is a sample of SGML for a generic chapter called chaptertitle: 
   <sect1 id="chaptertitle-additional-resources">
     <title>Additional Resources </title >
      <para>
       This should be a brief description of what is to follow.
      </para>
      <sect2 id="chaptertitle-installed-docs">
	 <title>Installed Documentation</title>
	<para>
	  <itemizedlist>
	    <listitem>
	      <para>
		<command>foo</command> man page —
		These sentence should be a description of what this man page contains.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<filename>/usr/share/doc/foo</filename> —
		These sentence should be a description of what this directory contains.
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>
      </sect2>
      <sect2 id="chaptertitle-useful-websites">
	<title>Useful Websites</title>
	<para>
	  <itemizedlist>
	    <listitem>
	      <para>
		<ulink url="http://www.redhat.com">http://www.redhat.com</ulink> —
	        This sentence should be a description of what this webpage contains.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<ulink url="http://www.redhat.com">http://www.redhat.com</ulink> —
  	        This sentence should be a description of what this webpage contains.
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>
      </sect2>
      <sect2 id="chaptertitle-related-books">
	<title>Related Books</title>
	<para>
	  <itemizedlist>
	    <listitem>
	      <para>
		<citetitle>Book Title</citetitle> by Author; Publisher  —
	        This sentence should be a description of what this book contains.
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>
      </sect2>
    </sect1>
In HTML, the above should look like the following:

Additional Resources

This should be a brief description of what is to follow.

Installed Documentation

  • foo man page — These sentence should be a description of what this man page contains.
  • /usr/share/doc/foo — These sentence should be a description of what this directory contains.

Useful Websites

  • http://www.redhat.com — This sentence should be a description of what this webpage contains.
  • http://www.redhat.com — This sentence should be a description of what this webpage contains.

Related Books

  • Book Title by Author; Publisher — This sentence should be a description of what this book contains.

4.8. Book References

When referencing a book, please use the following format:
In SGML:
<citetitle>Book Title</citetitle> by Author; Publisher
In HTML: Book Title by Author; Publisher For example, Maximum RPM by Edward Bailey; Red Hat Press.

Chapter 5. Avoiding Slang

Glossary
We write software documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straight-forward as possible, it is necessary to avoid slang and other culture-specific terminology. This page is an attempt to identify commonly-used slang terms and phraseology, and to provide alternatives.

Glossary

"anything you/they like"
This is probably readily understood but shouldn't appear in formal documentation.
"They can also use the slapi_register_plugin() call to register any kind of plug-in they like."
I rewrote it to be "...to register any other kind of plug-in."
"root your server in the /serverRoot directory"
This is not very elegant. Be aware of the multiple meanings of words. Try something like "Use the /serverRoot directory as the root directory for your server".
Check this site
Understood to mean "have a look at this website". The standard phraseology is something like "Refer to www.somewhere.com for more information". It is generally better to avoid "check" because it has so many meanings. Refer to the StandardTerminology page for more information.
dig deeper
Also - "delve deeper". "Visit the following web link to dig deeper into [subject]...". Using "dig deeper" may translate awkwardly. Instead, consider rewording to the suggested referral style in "check this", or to something like this: "For detailed information regarding [subject], refer to [internal link/external link]".
double-edged sword
Also - "double-bladed sword". If something is described as a double-edged sword, it indicates that it has two opposing behaviours or consequences. Instead, state that it can have unexpected consequences, or that the positive result might be offset by the negative result.
eat your own dogfood
Developer-speak. It means to use your own products. You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food
Fibs
A fib is "small lie", also known as a "white lie". This appeared in one of the GLS books: "this command tells fibs". Use something like "The output of this command can be misleading".
Flying by the seat of your pants
Generally understood to mean "reacting to events as they occur". Difficult to offer alternatives without context
frown upon
"To frown upon" means to hold in low regard, not to approve of, etc. This translates to (and should have been written as) ".. the use of session context is not recommended..." (or words to that effect).
fuzzy (search)
1. Even though "fuzzy" is slang, it's common when referring to searches, especially in databases. If you do a fuzzy search for "Smith" you will probably also get "Smyth", because it sounds the same. The use of "fuzzy" is valid in this context.
Note the difference between this and "wildcard" searches: "Sm?th" could return "Smith", "Smyth", "Smeth", or even "Smrth".
2. Don't use "fuzzy" to refer to something that is not clear, such as an image, a concept, an idea, etc. For example, "He was a bit fuzzy on the details" is not valid.
have a crack at
Have a crack at and jump right in are closely related in meaning as they imply to "get started or give it a try". Alternatives for these are "start/try/begin" and will depend on the context of what's being discussed.
in a pinch
Under a tight schedule, hard pressed to achieve something.
jump right in

See have a crack at.

Kettle of fish
Commonly used in the expression "a different kettle of fish", to mean, "that's a different matter (altogether)". Depending on the context, try to use "topic", "subject", "matter", or something similar.
Neologisms (Invented words)
The English language is full of these. Some of them are useful, some of them are less so, others are just painful, difficult to translate, and should be avoided. Many of them are the result of creating nouns from verbs, verbs from nouns, and adjectives from just about anything. Unless a particular word has been in use for some time and has been generally accepted into common English (for example, "kerberized", which refers to a Kerberos-aware application), try to avoid these neologisms. If necessary, reword or restructure your sentences.
Examples
* "This feature allows synchronization of adds, deletes, and changes ..."
o This sentence has converted three verbs to nouns. A better structure might be, "This feature allows the synchronization of add, delete, and change operations..."
over the wire
Commonly used in expressions like "password information is sent in plain text over the wire", meaning "sent unencrypted through the transmission medium" (whether it is a wired or wireless network, the Internet, or whatever). You probably don't need to say it at all. "Sent/transmitted in plain text" is fine.
pain in the backside
Nobody should ever write this or anything like it in any distributable documentation. Use something like "problematic", "difficult", etc., as appropriate.
Ready to Rumble
In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start".
right before doing something
It's better to use "immediately before doing something" or otherwise write around the phrase.
shoot yourself in the foot
To "shoot yourself in the foot" indicates that you have done something to harm your own cause, or acting against your own best interests. Just cut out the sentence - it should be self-evident from the surrounding information.
shy of
Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark", meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have less than the minimum number required. Avoid this terminology and use more easily understood terms; it will help our translators and also those reading our English documentation who are unfamiliar with such slang.
under the covers
This refers to something being out of plain sight or not immediately obvious. For example, you might only see the results of some action or command, but what happens "under the covers" is what is going on in the background, that you can't see or are not aware of, to make that action of command possible.
virtual elephants
This refers to a group of blind-folded people all touching different parts of an elephant and trying to describe what it is. Nobody sees the "big picture". It falls into the same category as "skeletons in the closet", "dark horse", "black sheep", etc. Use descriptions, adjectives, etc., that aren't specific to a particular culture or locale. Refer to http://en.wikipedia.org/wiki/Blind_Men_and_an_Elephant for more information.

Chapter 6. Cross References

This section contains suggestions on how to use cross-references in the most effective way, that is, so that it works for the reader, rather than the author. Formatting cross-references is not described in this section.
In the dark days of pure print documentation, cross-references pointed readers to additional or related information that existed elsewhere in the physical printed book; on other pages. The readers had to physically turn pages to find the referenced page, so authors and editors and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references or links in online documents today, the author must still do the work for the reader. It is still the author who must do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link could indicate that the author is writing for their own ease, and not for the good of the reader.
The Additional Information test — Is the cross-reference pointing to vital information or additional information?
A cross-reference should always point to additional information, not core information that the reader needs to perform the task at hand. For example, in a procedure to configure an application, do not merely provide a link to the appendix where the correct naming conventions are described. Give the reader examples and explanations of a valid filename, and at the end of the procedure provide the link to the appendix.
The Page Test — Is the additional information on a different page?
Do not cross-reference to text, sections, diagrams or tables on the same page. Use the power of words to direct the readers attention to the object. For example, "Table 1.1 displays valid return values" does not need an embedded link. If it exists, the readers will succumb to the temptation to click the link, and confusion will ensue as the same page is displayed.
Do not become a linkaholic!
The Reverse Test — Is the cross-reference pointing forwards or backwards in the document?
Prescriptive writing must always take the reader from the known to the unknown, so ideally, cross-references must always point backward. For example, a cross reference on page 50 that points back to page 25 meets the reverse test. A cross-reference on page 50 to page 75 fails this test. If it appears impossible to follow this rule, stop and think about the structure of the information. Does the reader really need to know this additional information right now? If yes, the information is not additional information, but vital information. Do the work and write the words to include the information. If not, that is, this is a "nice to know", point the reader back to the current page, page 50, from page 75.
Note: This rule does not apply to additional information in Appendices. For example, after describing an error message, it is acceptable to cross-reference to the Appendix E, which contains all the error messages. It is not acceptable to immediately point the reader to Appendix E and expect them to sort it out themselves.
The Information/Link Ratio — Does the paragraph/section consist largely of links?
In running text, there should not be more than a couple of links per paragraph. There should not be links in every paragraph, and there certainly must not be links in titles, subheadings, figure or table captions. Cross-references interrupt the flow of thought, and can actively interfere with the absorption of information. If the reader needs a lot of additional information, rethink the structure of the section, and enrich the quality of the information. Do not let the cross-references overpower the message. A solution is to add a sentence to the end of the section indicating where more information is available.
Note: Lists can be an exception, but try to provide the reader with a descriptive phrase or sentence for each cross-referenced item, as well as a lead-in and concluding sentence for the paragraph that contains the list.
The Repeatability Test — Does the information have to be repeated?
This is a hard one, and one that many authors abhor. Often the answer is yes. If the information is vital, and needs to appear in multiple places, it just has to be done. It's not a crime. In some circumstances, like online help, the reader wants the answer immediately. Do not force even one extra click on them. In a safety situation, it may be the only chance the reader has to find critical information quickly. Any vital information, that is not more than a couple of paragraphs, (or half a page, or 5 rows of a table) can be repeated rather than cross-referenced to.
Cross-referencing is a good servant but a poor master. Content still rules!

Chapter 7. Standard Terminology

Glossary
This page is an attempt to standardize some of the terminology and phraseology that we use in the RHEL documentation. Don't consider this as the final word by any means, but a set of guidelines.

Glossary

Asks for
Use "requests" instead.
By way of
Use "using" instead.
Examples:
  • connect one desktop or workstation to another by way of a host-to-host connection (incorrect)
  • connect one desktop or workstation to another using a host-to-host connection (correct)
For further/additional/whatever information
Use "For more information"
For instance
Use "For example"
For this reason
Use "therefore"
Gerunds
Everybody's favourite topic. The following is just an example of how it has been used, how it could be confusing, and how it could be improved:
  • For instructions on constructing iptables rules... Could be read as "how to get instructions while you're constructing iptables rules" (parallel operation)
  • For instructions on how to construct iptables rules... Less confusing
Giving Command Examples
  • Include a basic shell prompt, either for a normal user or for root, as appropriate.
  • Don't include the path unless it seems absolutely necessary. (Note: this refers to commands, not files.)
  • If you have two commands immediately following each other, they look better (in html at least) if they're contained in the same tag. i.e., don't have a pair for each command.
  • Try to use sensible names, or at least names that aren't confusing...
Examples:
  • [root@myServer ~ ] # chkconfig --level 345 iptables on
Lots of
Use "Several" or something equivalent instead.
Plurals
Dont's put "es" in parentheses to indicate plurals. I try to use this line of thought:
  • If it can only be singular, leave it singular
  • If it can be plural, make it plural
Examples:
  • Bind the IP address(es) to the appropriate port(s)
  • Bind the IP addresses to the appropriate ports
Sentence Syntax and Example Formats
The most common example I have come across is the way we use "Refer to xxx for more information". Sometimes it is written "For more information, refer to xxx", with other variations scattered around the place.
Technical Syntax
Functions
Take parameters and use syntax
Examples:
  • The myFunction() function takes the following parameters:
  • The myFunction() function uses the following syntax:
struct definitions
Contain fields and use syntax
Examples:
  • The ldapmod struct definition contains the following fields:
  • The ldapmod struct definition uses the following syntax:
Tells
Use "instructs", or "informs" instead, depending on the context.
Examples:
  • This option instructs the command to process all files in alphabetical order.
Within
Don't use to refer to a file that exists in a directory. Use "In".
Examples:
  • If the iptables file exists within the /etc/sysconfig directory... (Incorrect)
  • If the iptables file exists in the /etc/sysconfig directory... (Better)
  • If the /etc/sysconfig/iptables file exists, ... (Even better)

Chapter 8. XML Tags

It's not always logical which tag to use for something. I'm trying to help. You may disagree with some of the following, so feel free to ask about it and get it changed to something sensible. This is my thinking out loud and somewhere to keep things. It's not gospel or a rule book.
As always, refer to the docbook site for notes, other attributes and usage instructions. http://www.docbook.org/tdg/en/html/docbook.html
<citetitle>
Use citetitle when referring to an external book.
<cmdsynopsis>
This is a wrapper. Refer to the docbook website for how to use this. Essentially it's used for documenting the syntax of commands (rather than actual examples), and listing the various possible arguments, their class, etc.
<command>
commands
  • (e.g.) ls, top, find, mount, bash
  • Other cases as well may require the use of this tag if nothing better presents itself.
  • Don't use this tag for things like filenames, directories, etc.
  • Note the use of this tag for /bin/bash - don't use <application> in this case. This is used for larger software packages, e.g., Inkscape, acroread.
<filename>
files and directories
  • Use <package> where appropriate, however.
<guilabel>
GUI objects
  • Apart from traditional usage as described in the ?DocBook Guide, use this for dialog boxes, screens, and windows that appear on-screen as well.
  • Do not use <interface>; as of ?DocBook v3.0 it is obsolete.
<literal>
Attribute values
  • Values of attributes, etc. For example, the nsslapd-accesslog-level attribute can have values of 0, 4, 256, and beyond. I used <literal> tags for these values.
  • <option> is a possibility as well, if you think about attributes/parameters being on or off. If you find a better one, please let me know.
<option>
command options, etc.
  • On occasion you might need to list a number of options for a command or something similar. These should be tagged as options, not commands.
  • Note that this is not used for actual command examples. Do not create an example such as "ps aux | grep bash" and tag the individual components. Tag the entire command as <command>. See also <cmdsynopsis>
  • This tag does not mean "optional"
<parameter>
Parameters of any kind
  • Use <parameter> for attributes, (as distinct from object classes, for which I used <classname>).
  • Also for command arguments, where (for example) you need to list and describe command arguments. I haven't found anything better yet.
  • I also used <parameter class="option"> for allow and deny permissions/privileges.
  • <parameter role="entry">cn=kerberos</parameter>
<programlisting>
Use this for code samples (anything that is typed into a text editor) ... and then use <screen> for the output.
<property>
I started using this when referring to (e.g.,) Group Name, GID, and UID of users in the IPA documentation.
<returnvalue>
Fairly obvious I guess, but I've seen it marked up as various other things. It just refers to the value returned by a function or something similar, with typical values being 0 (zero) or -1, etc.
<screen>
For anything that is shown on a screen ... usually output from a command. Do not use for code samples.
<systemitem>
This tag supports a range of classes that can be used for various things, such as protocols, resources, and user account names. Also use for less easily-definable objects, such as PAM and kernel modules, with 'role="module"'.
  • Example: <systemitem class="username">root</systemitem>
  • Example: <systemitem class="server">europe.example.com</systemitem>
  • Example: <systemitem role="module">pam_mkhomedir</systemitem>
  • Example: <systemitem class="resource" nfs/<FQDN></systemitem>
Note:
  • These examples are context dependent. In a different case, the "server" class might be "domainname".
  • For services (e.g., httpd, etc.), use class="service" rather than class="daemon". Trying to determine when to use one rather than the other in doc at present doesn't appear to be worth the effort...
<type>
Data types for parameters

Chapter 9. Resources

Bibliography
Books, websites, and people for you to consult on your quest to create the perfect document.

Bibliography

Dictionaries of American English

The American Heritage Dictionary of the English Language, Fourth Edition. Houghton Mifflin . Boston . 2009. An online edition is accessible free of charge through http://www.thefreedictionary.com/.

Merriam–Webster Online. http://www.merriam-webster.com/. There is no charge for access to a basic, abridged version. Access to the unabridged version is available at $US 30 per year.

The New Oxford American Dictionary, Second Edition. Oxford University Press . 2001.

The Oxford American Dictionary of Current English. Oxford University Press . 2002.

The Oxford Dictionary of American Usage and Style. Oxford University Press . 2000.

Dictionaries of IT terms

http://www.computeruser.com/resources/dictionary/index.html.

http://webopedia.internet.com/.

A Dictionary of Computing, Sixth Edition. Market House Books . 2008.

A Dictionary of the Internet. Darrell Ince. 2009.

General style guides

AP Stylebook. The Associated Press . New York . 2009. Online version available at http://http://www.apstylebook.com — subscription $US 25 per year.

Publication Manual of the American Psychological Association, Sixth Edition. American Psychological Association . Washington DC . 2009.

The Chicago Manual of Style, 15th Edition. The University of Chicago Press . Chicago . 2003. Online version available at http://www.chicagomanualofstyle.org/home.html — subscription $US 30 per year.

MLA Handbook for Writers of Research Papers, Seventh Edition. The Modern Language Association of America . New York . 2009. Available from http://www.mlahandbook.org for $US 22, which includes access to the online version of the guide for the lifetime of the Seventh edition.

Working With Words: A Concise Handbook for Media Writers and Editors, Third Edition.. St. Martin's Press . New York . 1997.

IT style guides

Apple Publications Style Guide. Apple . Cupertino . 2008. PDF version available at no cost online from http://developer.apple.com/mac/library/documentation/?UserExperience/Conceptual/?APStyleGuide/APSG_2008.pdf.

IBM Style, Sixth Edition. IBM . 2004. At various times, a PDF version of this book has been available at no charge online; most recently at http://www-03.ibm.com/easy/page/1387/$File/IBM_Style.pdf — this link is not working as of October 2009.

Microsoft Manual of Style for Technical Publications, Third Edition. Microsoft . Redmond . 2004. Previously, an electronic version of this book was available at no charge online as a Compiled HTML Help (CHM) file from the Microsoft website; this is not presently available in October 2009.

Read Me First! A Style Guide for the Computer Industry. Sun Microsystems . Mountain View . 1996.

Wired Style: Principles of English Usage in the Digital Age. Broadway Books . New York . 1999.

Revision History

Revision History
Revision 0Thu Aug 26 2010Rüdiger Landmann
Initial creation of book by publican
Import content from wiki

Index

F

feedback
contact information for this manual, We Need Feedback!