Punctuation and Grammar
Use standard grammar, punctuation, and spelling. Although published documents are edited and proofread, not all errors get caught, and such errors distract readers from the content of the writing. Authors of documents should do the first proofreading.
Punctuation
Here are a few notes about punctuation conventions.
Commas
Use a comma to separate items in a series of three or more items. Always place a comma before the ”and” or “or.” For example:
tables 2, 3, and 4
Note: For technical publications and on the ITS Web site, we always apply this punctuation style. Omitting the comma in technical documents can introduce ambiguity, something we wish to avoid. In order to be consistent, we apply the rule to all phrases, regardless of their simplicity. In promotional pieces and other types of publications, however, you may notice that we omit the last comma in the series, which is the journalistic style.
Place Names: Use a comma to separate a city from a state, For example: Austin, Texas
Names and Titles of Persons: Use a comma between the name and title of a person. For example: The scheduled speaker is John Doe, manager, Information Technology Services.
Numbers: Use a comma in quantities of 1,000 and more unless the number is a year, page number, temperature, radio frequency, byte number, or baud rate. For example: 1,300 pounds and 1200 bytes.
After introductory modifiers like this, you should use a comma.
You should add a comma before an afterthought, as in this case.
Use a comma before coordinating conjunctions (and, but, or, nor, so) that join two complete predications (subject + verb). For example:
The software has been installed, and it is now ready for use.
But do NOT use a comma if the coordinating conjunction is NOT joining two complete predications:
The software has been installed and is now ready for use on UTS.
Use commas to set off appositives:
The new software package, GODZILLA, has no documentation.
Use commas to set off nonrestrictive clauses (items that do not restrict the central meaning of the sentence). For example:
The new software package has no documentation, which makes it difficult to use.
For restrictive clauses—clauses that are essential to the central meaning of the sentence—use no commas, and use that instead of which. Compare the following:
The magnetic tape that you sent us is unreadable.
The magnetic tape, which you sent us, is unreadable.
Semicolons
Use a semicolon to separate two closely related independent clauses that are not joined by a coordinating conjunction, such as and, or, or but.
In general, use a semicolon only where you can use a period. A semicolon is NOT a strong comma. It is frequently used to join two complete predications (subject + verb) when the second predication starts with specific words, such as however, therefore, or nevertheless. For example:
The software will be installed on May 1st; however, it will not be available to users until May 15th.
The above use does not break the general rule: . . . only where you can use a period.
You should also use semicolons to separate items in a series when such items have internal punctuation that would cause confusion, as in a nested series. For example:
The package contains routines for numerical analysis; text editing, formatting, and processing; and statistical analysis.
You may also be able to break a nested series into a bulleted list for easier reading.
Colons
The most common use of a colon is before an example or list. For example:
The following software will be removed:
Windows 3.1
Windows NT
Mac OS 7
Word Perfect
In a sentence, a colon generally means that is. Thus:
The Student Microcomputer Facility will be closed for the entire week: 29 April through 5 May.
Quotation Marks
Follow standard American English usage and put commas, periods, and other punctuation inside quotation marks. To refer to words as words, use italics instead (Spamming is not the same as mail-bombing).
The only instance where you should place punctuation outside of quotation marks is when you are providing a string of text for the user to enter, and you need to prevent the user from including the marks:
At Microsoft Exchange Server, enter "austin.utexas.edu".
To prevent users from misinterpreting punctuation marks as part of a command's syntax, use boldface type to differentiate commands or menu items from the rest of your sentence:
From the File menu, select Open.
You can use opening quotation marks and closing quotation marks, often referred to as smart quotes, but always use ordinary ASCII quotation marks (") when they are needed in command lines and other user input samples. Otherwise, users may type the wrong characters, trying to duplicate what they see in the document.
Em-dash
In general, the em-dash should be avoided in technical writing. If you find yourself tempted to use it, try rewriting the sentence. You may find it in feature articles, marketing material, the occasional style guide, or other publications. Do not use spaces around the em-dash:
BevoWare is an important—some would say critical—component of keeping our campus network secure.
En-dash
In general, the en-dash is unnecessary in technical writing for the Web or general publication. In high-end marketing or promotional material, the en-dash is used in a number range.
Grammar
Tense
Use the present tense when describing current or habitual actions and responses. In technical documentation, it is rarely appropriate to use the future tense. For example, say the program prompts instead of the program will prompt.
Enter your EID and password. The PADlock program asks you to enter an additional password.
If you use Word to write your technical documentation, you should update regularly.
Active voice
Use the active or imperative voice instead of the passive voice. Instead of saying
The q option must not be specified by users
say
You must not specify the q option
or
Do not specify the q option.
Use the active voice when you want to focus on the subject performing the action. For example:
The PPI register and the memory address register share port 3.
The active voice is preferred in technical documentation. It is, however, sometimes appropriate to focus on the subject that receives the action. For example.
Port 3 is shared between the PPI register and the memory address register.
Possessives
Distinguish between singular and plural possessives: a user's needs but all users' needs. Use singular in titles that have phrases, such as User's Guide or User's Reference List. Remember that it's is NOT a possessive, but a contraction of it is.
Comparatives
Don't use comparative forms of words without indicating what comparison is being made. For example, when you say something is more efficient, specify what it is more efficient THAN.
