5. Mechanics of Writing


This section reviews basic punctuation rules and guidelines for the English language, and notes exceptions that are specific to computer documentation.

Note - Traditional punctuation marks take on specialized meanings in the context of programming languages. A classic example is that of quotation marks in the C shell or Bourne shell, which provide specialized, non-intuitive meanings for single quotes (`), double quotes ("), and back quotes ('). Watch for these in your writing and editing.



Use an apostrophe:


      Class of '66
      Spirit of '76

    If they do not end in "s," add an apostrophe and an "s" to most indefinite pronouns, singular nouns (including collective nouns), and plural nouns.

      the file's properties
      someone's system
      the group's privileges
      women's rights

    To form the possessive of singular nouns ending in "s" (or its sound), you often add an apostrophe and an "s."

      the mouse's buttons
      the bus's capacity

    When the addition of an "s" produces an awkward sound, add only the apostrophe.

      ACME Systems' employees

    In a few cases, however, either is acceptable.

      M. Travis's files
      M. Travis' files

    Add an apostrophe to form the possessive of plural nouns that end in "s."

      the Travises' files
      the boards' interrupts

    Add an apostrophe and an "s" to the last word of the compound to form the possessive of most compound constructions.

      each other's files
      anyone else's business

    The possessive of two or more proper nouns depends upon ownership. In the first example, ownership is joint; in the second, individual.

      Malcolm and Mary's files
      Malcolm's and Mary's files

      drive B's
      ~'s and #'s
      - f's

    The plural possessive of single lowercase letters and single uppercase letters will be awkward in the plural possessive form. A rewrite often can avoid this situation.

      The dots on the "i's."
      The "i's'" dots.

    The apostrophe is not necessary (although not incorrect) when you are forming the plural of two or more unitary uppercase letters or numerals.

      plug in all CPUs
      the operating system of the 1990s


Brackets are not substitutes for parentheses. To preserve brackets' unique service as meaningful signals to readers of computer documentation, construct sentences in a way that minimizes the grammatical need for such punctuation.

Use brackets:

      It often makes sense to place comments within a menu file (see page 154 of Advanced Skills, Revision A [May, 1991] for more information).

      date [yymmddhhmm]


Use a colon:

    Note that the colon takes the place of introductory phrases such as "as follows" and "listed below."

      Default settings include four secondary groups: operator, devices, accounts, and networks.

      Three options available from the Diagnostics menu are:

    When the introduction to a list or steps in a procedure is a complete sentence, use of the colon is optional. However, judge whether the ensuing list seems to flow naturally from the introduction; in effect, to "complete" the introductory sentence. If so, use a colon.

      Learn how to send a message by following these steps:

      To send a message:

      Follow the steps in the next exercise to learn how to mail a message.

    The colon serves as a substitute for phrases such as "in other words," "namely," or "for instance."

    Notice in the following example that the first word following the colon is capitalized. Capitalize the statement if it is a complete sentence; don't capitalize it if it's a fragment.

      It was a software package doomed from the start: Its price was $12,000, its language written in ALGOL, and its documentation was printed on 300 sheets of unbound paper.

      Here is the choice: Do you want to save the file or delete it?

      Remember this cardinal rule: Never reboot your system until you've saved all of your files.


Use a comma:

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

    Use a comma before the conjunction that joins the last two items of a series.

    In complex sentences, however, elimination of the final serial comma sometimes helps to separate a long series from an independent clause.

      Before going to the next step, position the pointer on the desktop, display the menu, make your selection and confirm the result, and you will ensure the accuracy of your data.

    However, if an independent clause already contains a comma, use a semicolon to separate items in a series.

      The window has a menu bar, which lists available menus; a palette, which shows graphics tools; and a working area, where you draw.

    A comma separates independent clauses joined by the coordinating conjunctions "and," "but," "yet," "for," "nor," and "or." Place the comma before the conjunction.

      You don't have to back up your files, but doing so is prudent.

      She lost all of her work, yet she still doesn't back up files.

    Omit the comma between two short independent clauses in a sentence.

      Back up your work or you're fired.

      Display the menu and choose Save.

    Use a comma to separate a subordinate clause or long introductory phrase from the rest of the sentence.

      Using the text editor, change the last line of the file.

      By recording transactions and automating billing, the financial software saves time and prevents costly errors.

    Use a comma after a dependent adverbial clause that starts a sentence, but not if the clause appears in normal order in the sentence.

      Because this feature automatically updates system files, it saves time.

      This feature saves time because it automatically updates system files.

    A comma separates an introductory modifier from the rest of the sentence.

      Hopefully, he entered the personnel office.

      Confident she had saved her work, she logged out.

    A comma sets off introductory interjections or transitional words.

      Oh, did you need more information?

      Fine, go ahead and set up that meeting.

      The mail icon, which looks like a mailbox, flashes.

      Writers often refer to this book, which is a style guide for the computer industry.

      The software, with its simple interface, will decrease input time by 50 percent.

      Write to ACME Systems, Santa Maria, California.

      The monitor, hardware that looks like a television set, has only one function.

      She was hired on January 1, 1989, and left six months later.

      :She was hired in January 1989.

Dash (Em Dash)

Use an em dash, with no space before or after the dash:

      Three vital pieces of hardware - the keyboard, the system unit, and the monitor - are packed in the largest carton.

    Use of dashes in the example above avoids the confusion that could be caused by using commas both within the series and to set off the series from the rest of the sentence.

    In most cases, use commas instead of dashes to set off a single appositive.

      The monitor, hardware that looks like a television set, sits on top of the system unit.

      Log in to the system - but that's an obvious first step.

      Become superuser - you must type su to do this - and delete all files in M. Travis's directory.

      All of the options - Create, Modify, and Save - enable you to customize the software's features.

Dash (En Dash)

Use an en dash:

      Refer to pages 16 - 24.

      Do not operate this equipment in temperatures lower than - 10 °C.

      The word processing software features:

Ellipsis Mark

An ellipsis mark comprises three ellipsis points (periods) with a space between each point. A space separates the ellipsis mark from preceding and subsequent text and punctuation.

Use an ellipsis mark:

      When the system displays, "Do you want the . . . settings now?"

    Add a period when a complete sentence ends with an ellipsis mark or when you have omitted entire sentences from quoted matter. In effect, you type four periods, each preceded by a space.

      You see this message on the screen: "If you like, you may press the Stop key . . . ."

      The system then displays this message: "This system is being configured . . . . When this system is configured, it will finish booting."

      Reformatting page. Wait . . .


Because the computer industry has developed unique terminology, the use of hyphens has become troublesome. Computer documents are often littered with unnecessary hyphens. Refer to Table 5-1 for a list of words and phrases that have come into general acceptance as hyphenated, unhyphenated, or compound.

If you can't find a specific word or term in the table, apply this general rule: Hyphenate a multiword expression when used as a modifier; do not hyphenate the expression when used as a verb or noun.

    the check-in procedure
    check in the material

    the direct-access password
    if you have direct access

    the end-user application
    writing for end users

This section includes guidelines for when to use a hyphen and when not to use a hyphen.

Use a hyphen:

      This applies only to user-defined functions.

      Print your 500,000-byte file.

    Hyphenate a compound modifier when it appears before the noun. Usually, when it appears after the noun, a compound modifier should not be hyphenated.

      An easy-to-remember mail alias is a person's first initial and last name.

      A mail alias that is easy to remember is a person's first initial and last name.

    Occasionally, the initial elements of two or more compound modifiers within the same sentence share the same final element. In these constructions, hyphenate the initial elements, even when they are not joined directly to the final, common element.

      The sending application and the receiving application expect 8- and 7-bit characters, respectively.

      These computers have file-, directory-, and labor-saving features.

      "Ed owns a toy-repair store" vs. "Ed owns a toy repair store"

      "He recovered the disc" vs. "He re-covered the disc"

      re-enable, co-organizer, shell-like, reentry, unnumbered, misspell

    Use a hyphen to join numbers and proper nouns or adjectives with the following prefixes. (These same prefixes, however, are usually joined without hyphens to common nouns and modifiers.)

      anti- mid- neo- non-
      pan- pro- un-

    Almost without exception, hyphens join the following prefixes with the main word of a compound.

      all- ex- self-

      The resulting core file will take up nearly one-third of your system memory.

      Press Control-Shift-q.

Do not use a hyphen:

      backup, database

      Dial up only after reading the dial-up instructions.

      Look up the value in the look-up table.

      An easily remembered mail alias is a person's first initial and last name.

      Your file comprises 500,000 bytes.

      bi inter meta micro mini multi
      non pre post un under

      Refer to pages 16 - 24.

    Table 5-1 Hyphenation Guidelines

Word or Phrase       Usage
add on               verb
add-on               noun, modifier
all-inclusive        modifier
alphanumeric         modifier
analog-to-digital    modifier
antiglare            modifier
automount            verb
autotransformer      noun
back panel           noun
back-panel           modifier
backplane            modifier, noun
backquote            modifier, noun
backslash            modifier, noun
backspace            modifier, noun, verb
back up              verb
backup               modifier, noun
bandwidth            modifier, noun
benchmark            modifier, noun
bidirectional        modifier
bisynchronous        modifier
bitmap               modifier, noun
bitstring            modifier, noun
breakpoint           modifier, noun
build in             verb
built-in             modifier
card cage            noun
CD-ROM               noun, modifier
check in             verb
check-in             noun, modifier
checklist            noun
check out            verb
check-out            noun, modifier
client-server        modifier
coaxial              modifier
code name            noun
colormap             modifier, noun
command line         noun
command-line         modifier
compact disc         noun
coprocessor          modifier, noun
coroutine            modifier, noun
cross-refer          verb
cross-reference      noun 
cross-section        noun
cross-sectional      modifier
database             modifier, noun
datasheet            modifier, noun
datastream           modifier, noun
daughterboard        modifier, noun
debug                modifier, noun, verb
deselect             verb
desktop              modifier, noun
dial up              verb
dial-up              modifier
digital-to-analog    modifier
direct access        noun
direct-access        modifier
directory name       noun
double click         noun
double-click         modifier, verb
download             verb
downtime             modifier, noun
drag and drop        noun
drag-and-drop        modifier
dual-access          modifier
dual-density         modifier
dump file            noun
electromagnetic      modifier
email                modifier, noun
endpoint             noun
end user             noun
end-user             modifier
entry level          noun
entry-level          modifier
feedback             noun
file name            noun
file server          noun
file sharing         noun
file-sharing         modifier
file system          noun
firmware             noun
fixed length         noun
fixed-length         modifier
fixed point          noun
fixed-point          modifier
floating point       noun
floating-point       modifier
flowchart            modifier, noun
follow up            verb
follow-up            modifier
frame buffer         noun
front end            noun
front-end            modifier
front panel          noun
front-panel          modifier
full height          noun
full-height          modifier
general-purpose      modifier
grayscale            modifier, noun
half-height          modifier
hard copy            noun
hard-copy            modifier
hardwire             verb
hardwired            modifier
hexadecimal          modifier
high end             noun
high-end             modifier
high level           noun
high-level           modifier
high performance     noun
high-performance     modifier
high resolution      noun
high-resolution      modifier
high speed           noun
high-speed           modifier
host name            noun
host-name            modifier
hot key              noun
hotline              modifier, noun
in-line              modifier
inode                noun
interconnect         modifier, noun, verb
interface            modifier, noun
internetwork         modifier, noun
interoperability     noun
interprocess         modifier, noun
keyboard             modifier, noun
keymap               modifier, noun
keypad               modifier, noun
keyword              modifier, noun
laser disc           noun
left-justified       modifier
list file            noun
local-area           modifier
lock up              verb
lockup               modifier, noun
log file             noun
log in               verb
login                modifier, noun
log out              verb
logout               modifier, noun
look up              verb
look-up              modifier
low end              noun
low-end              modifier
low level            noun
low-level            modifier
low resolution       noun
low-resolution       modifier
lowercase            modifier, noun
mailbox              noun
mainframe            modifier, noun
mass storage         noun
mass-storage         modifier
metadisk             modifier, noun
metafile             modifier, noun
microcode            modifier, noun
microprocessor       modifier, noun
microsecond          noun
midrange             modifier, noun
minicomputer         modifier, noun
miniroot             noun
monochrome           modifier
motherboard          modifier, noun
multilevel           modifier
multimedia           modifier, noun
multiplexer          modifier, noun
multiprocessor       noun
multitasking         modifier
multitrack           modifier, noun
multiuser            modifier
newline              modifier, noun
node name            noun
noninterlaced        modifier
nonproprietary       modifier
nontechnical         modifier
nonzero              modifier
object-oriented      modifier
off line             adverb
off-line             modifier
off-load             verb
on-board             modifier
on line (or online)  adverb
on-line (or online)  modifier
path name            noun
path-name            modifier
pop-up               modifier
print out            verb
printout             modifier, noun
pull-down            modifier
pull-right           modifier
random access        modifier
raster file          noun
raster-file          modifier
read-only            modifier
real time            noun
real-time            modifier
re-create            verb
restart              verb
retry                verb
right-justified      modifier
runtime              modifier, noun
SBus                 noun
scrollbar            noun
self-test            modifier, noun
set up               verb
setup                modifier, noun
shut down            verb
shutdown             modifier
single-tasking       modifier
source code          noun
source-code          modifier
source file          noun
source-file          modifier
standalone           modifier
start up             verb
startup              modifier, noun
subdirectory         noun
subentry             noun
subroutine           modifier, noun
subset               modifier, noun
subsystem            modifier, noun
subtest              noun
superblock           noun
supercomputer        modifier, noun
superuser            noun
2-D                  modifier
3-D                  modifier
text-only            modifier
time-out             modifier
timesharing          modifier, noun
timestamp            noun
time zone            noun
token ring           modifier
toolkit              modifier, noun
tradeoff             noun
triple-height        modifier
troubleshoot         verb
troubleshooting      modifier
upload               modifier, verb
uppercase            modifier, noun
uptime               noun
user ID              noun
user name            noun
video disc           noun
wide-area            modifier
wildcard             modifier, noun
word processing      modifier
workgroup            modifier, noun
worksheet            noun
workspace            modifier, noun
workstation          noun
write-back           modifier
write-enable         verb
write-enabled        modifier
write-protect        verb
write-protected      modifier
Z-buffer             noun


Before using parentheses, consider whether the parenthetic material is, in fact, important enough to be included at all. If it is, perhaps the text fits better without parentheses within the paragraph. If the information is not important, don't write it.

Use parentheses:

      The Font menu, which provides four options (Regular, Italic, Bold, Bold Italic), is easy to use.

      You can save these settings in a "quick-start" file (explained fully in the next step) to load them automatically.

      To suppress the printing of address information (particularly useful for messages with many addresses), remove the check from the Print Header box.

      Choose from (a) keyboard entry, (b) mouse entry, and (c) voice entry.

      Choose from (a keyboard entry, (b mouse entry, and (c voice entry.

      The operating system inserts a tilde (~) when a file name is too long.

      The software package tracks maintenance on your heating, ventilating, and air conditioning (HVAC) systems.

    Whole paragraphs should never be parenthetic.

      Position the pointer on the top scrollbox and click the left mouse button. (For detailed instructions on scrolling windows, see page 33.)


Use a period:

      The procedures are in the howto.doc file.

      The ls -a command lists .cshrc and .orgrc among your hidden files.

    In the UNIX system, a period also serves as an abbreviation for the current directory.

      To copy a file into the current directory, type cp ~/work/budget .

      Computer documentation is always grammatically precise.

    Whenever possible, avoid ending a sentence with a verbatim command that the must be typed. A reader might misinterpret the sentence's ending punctuation as an integral part of the command.

      "Type boot to restart the computer." vs.
      "To restart the computer, type boot."

      The meeting is at 10 a.m. on Friday.

Quotation Marks

Use quotation marks:

    Don't enclose verbatim commands, system messages, file names, and so forth in quotation marks. In some cases a reader may be misled into thinking that the quotation marks are an integral part of what is to be typed.

      The comment in the .login file states that the file is "read in when you exit from the login shell."

      For more information about editing mail, see Chapter 5, "Sending and Receiving Mail."

      You can use the tee command to take a "snapshot" of your keystrokes.

      The word "menu" is often used in technical writing.

      The letter "x" denotes . . . .

No single rule governs the placement of quotation marks that are next to other punctuation marks. Whether the final quotation mark follows or precedes another punctuation mark depends upon context.

      "Yes," he replied, the program is written.

      There are three buttons on your "mouse": left, middle, and right.

      Some of your files are "hidden"; that is, their names do not appear in a standard ls directory listing.

      The system prompts, "Do you want to continue?"

      The user guide answers the question, "What does it do?"

    But place the final quotation mark before a question mark or exclamation point that is not part of the quoted material.

      How do I display a list of files that are "hidden"?


Use a semicolon:

      The Open key is a toggle key; that is, a key with alternating functions.

      Some of the options are not available; for example, the Undo option is grayed out and the Spell option is not displayed.

      Because this software is supplied in source-code form, users may adapt it for use on other systems; however, modified source code is not supported by ACME Systems.

    A semicolon also separates independent clauses not joined by a conjunction.

      Don't write the introduction; all introductions are now written by Marketing.

      The Reply button provides the following options: Reply (all), include; Reply, include; Reply (all); and Reply.