5. Mechanics of Writing

Punctuation

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.

Topics

Apostrophe

Use an apostrophe:

      can't
      aren't
      it's
      you're

      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

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]

Colon

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.

Comma

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

Hyphen

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
------------------------------------------
A                    
                     
add on               verb
                     
add-on               noun, modifier
                     
all-inclusive        modifier
                     
alphanumeric         modifier
                     
analog-to-digital    modifier
                     
antiglare            modifier
                     
automount            verb
                     
autotransformer      noun
                     
B                    
                     
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
                     
C                    
                     
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
                     
D                    
                     
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
                     
E                    
                     
electromagnetic      modifier
                     
email                modifier, noun
                     
endpoint             noun
                     
end user             noun
                     
end-user             modifier
                     
entry level          noun
                     
entry-level          modifier
                     
F                    
                     
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
                     
G                    
                     
general-purpose      modifier
                     
grayscale            modifier, noun
                     
H                    
                     
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
                     
I                    
                     
in-line              modifier
                     
inode                noun
                     
interconnect         modifier, noun, verb
                     
interface            modifier, noun
                     
internetwork         modifier, noun
                     
interoperability     noun
                     
interprocess         modifier, noun
                     
K                    
                     
keyboard             modifier, noun
                     
keymap               modifier, noun
                     
keypad               modifier, noun
                     
keyword              modifier, noun
                     
L                    
                     
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
                     
M                    
                     
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
                     
N                    
                     
newline              modifier, noun
                     
node name            noun
                     
noninterlaced        modifier
                     
nonproprietary       modifier
                     
nontechnical         modifier
                     
nonzero              modifier
                     
O                    
                     
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
                     
P                    
                     
path name            noun
                     
path-name            modifier
                     
pop-up               modifier
                     
print out            verb
                     
printout             modifier, noun
                     
pull-down            modifier
                     
pull-right           modifier
                     
R                    
                     
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
                     
S                    
                     
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
                     
T                    
                     
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
                     
U                    
                     
upload               modifier, verb
                     
uppercase            modifier, noun
                     
uptime               noun
                     
user ID              noun
                     
user name            noun
                     
V                    
                     
video disc           noun
                     
W                    
                     
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                    
                     
Z-buffer             noun
------------------------------------------

Parentheses

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

Period

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"?

Semicolon

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.

      
      
      
      
(Continued...)