1

CSc 190 - Senior Project

Writing Software Documentation

Some Guidelines

http://gaia.ecs.csus.edu/~buckley/CSc190/WritingGuide.pdf

2

Technical Documentation

Known Problems

Surveys say:

• Lack of audience definition

• Poor structure

• Disdain for the reader

• Unclear writing

• Poor use of illustrations

3

Technical Writing

• Be clear about what exactly is the purpose of the

document you are writing.

– This means, who is going to read it and why.

• Use the “Map” Analogy

– Think of reader undertaking a journey… the reading of

your document.

– You are supplying a well annotated map for that reader.

• Remember the Technical Writer’s Golden Rule

Always put yourself in the reader’s place.

4

Basic Solutions

• Understand your audience

• Address the reader directly

• Keep the information manageable

• Use illustrations wherever possible

• Don’t just write, rewrite (it’s a process!!)

• Give readers access to what they want

• Make sure the facts are accurate

• Allow for readability factors

5

Senior Project Style Manual

All documents will have an Introduction as the first section. This serves as the “executive summary” for the document… as such, it should be written last.

1 Introduction.

1.1 Purpose.

1.2 Scope.

1.3 Definitions, acronyms, abbreviations.

1.4 References.

1.5 Overview.

Glossary

6

Numbering Sections and Subsections

1

1.1

1.1.1

1.1.2

1.1.2.1

1.1.2.2

1.1.2.2.1

1.1.2.2.2

• Headings should clearly describe the contents of

the section or subsection.

• Section Headings in UPPER CASE.

• Subsection Heading words capitalized.

• Section Headings and Subsection Titles in BOLD

and ending with a period.

– Section text begins as a new paragraph

– Subsection text follows heading on same line.

• Referencing: (see Section 1) or (see 1.1.2.1).

7

Page Numbers and Spacing

• Header and Footer Information

– Include Page Number

– Options:

• Title of document

• Date

• Revision number

• Team name

• Spacing

– Body is single spaced

– Paragraphs separated by blank line

8

Lists

Bulleted List

•

•

•

•

•

Numbered Numbered list

List with Sublist

(1) (1)

(2) (a)

(3) (b)

(2)

No punctuation

One list per section/subsection

9

Tables and Figures

• Number each Table or Figure followed by

appropriate title.

Table 1 Figure 1

Table 2 Figure 2

Table 3 Figure 3

• Cite tables and figures in the text by

specifying Table or Figure followed by the

number.

Examples: see Table 6

see Figure 10

10

APPENDICES

APPENDIX A: < title >

• Section and subsections begin with the appendix

letter (e.g. A.1, A.1.1, A1.2, etc.)

• Must be referenced in the body of the document

• Useful by not essential information

not essential does not mean unnecessary!

it means not essential for understanding the content

in each of the sections!

• Use appendices for information that does not fit in

logically, or only needs to be referenced.

11

Glossary

• Definitions, Acronyms and Abbreviations

• Used in the document to save time and space, but only if

their meaning is unquestionably clear to the reader.

• Abbreviations and Acronyms

First appearance – do not use the abbreviation or acronym

Spell it out! ...with the abbreviation or acronym in parentheses.

e.g. Software Requirements Specification (SRS) document

Subsequent references can then use the acronym or abbreviation

12

Citing References

• Format

Book [1] Rumbaugh, J., M. Blaha, W. Premerlani, F. Eddy, and W. Lorensen. Object-Oriented Modeling and Design. Englewood Cliffs, NJ: Prentice Hall. 1991.

Article [2] Suchman, L. “Representations of Work.” Communications ACM 38, 9 (Sept. 1995): 33-34.

Reference [3] Institute of Electrical and Electronics Engineers, Inc. IEEE Standard for Developing Software Life Cycle Processes. ANSI/IEEE Std 1074-1991.

• References are listed in subsection 1.4 of each document.

• In the body of the document, references should be cited where applicable, with reference number in brackets

for example, [1]

http://www.mla.org/

Document from a Web Site

• Author. "Title of Web Page." Title of the Site.

Editor. Date and/or Version Number. Name of

Sponsoring Institution. Date of Access <URL>

• Sherman, Chris. "Everything You Ever Wanted to

Know About URL." SearchEngineWatch. Ed.

Danny Sullivan. 24 Aug. 2004. 4 Sept. 2004

<http://searchenginewatch.com/searchday/article.p

hp/3398511>.

13

Standardized Style

• All documents produced by the team must have

the same style… the same “look and feel” to the

reader.

• Standardize

Title Page

Headers and Footers

All of what was described above

14

15

Myth of the Perfect Draft

“You can produce a nearly final version of your

document in one attempt.”

Not true!!!

At least 50% or your writing time is (should be)

re-writing and editing.

16

Revising tips…

Don’t edit as you write…

Go back a reread – is the message clear!

Some questions to answer:

1. Is the purpose immediately clear to the reader?

2. Is the message relevant to the reader?

3. Does each new thought make sense?

4. Do the thoughts “flow” smoothly and logically?

5. Are the thoughts clearly expressed?

17

More…

Strengthen your message!

1. Is the message complete

2. Are the words appropriate

3. Is the tone correct?

and Condense (shorten) your message.

Style

• Using the right tense

• Clarity

• Controlled English

• Sentence length

• Pompous style

• Technical terms & jargon

• Variety and inconsistency

• Numbers in text

• Using highlighting

• Capitalization

• Colloquialisms & slang

• Humor

• Using “he” or “she”

• Using “must”, “should”,

“can”, or “may”

• Acronyms & abbreviations

• Punctuation

• Point of View

18 Find a good technical writing reference text… you

will learn why you need to use it.

Using the right tense

• Present tense - typical

• Past tense – sometimes when communicating

background information

• Future tense – only when describing expected

results

“A READ statement is used to assign the listed variables

those values which are obtained from a DATA statement.”

19

20

Active and Passive Voice

VOICE: the way the subject (the doer) of the sentence is

related to the action expressed by the verb.

Active voice: to the point, sharp and clear

Examples:

PASSIVE:

The selection of this operation is made automatically by the

software if there is no intervention by the operator.

ACTIVE:

Unless the operator intervenes, the software selects this function

automatically.

21

Active and Passive Voice

PASSIVE

“The program can be started by double clicking on the icon.”

ACTIVE

“Double-click on the icon to start the program.”

Note: Passive voice can be used if the doer in the

sentence is unimportant!

The sixteen bits of each word are numbered 0 to 15.

The I/O units are both shown in Figure 2.

The address of the File Control Block becomes the next free

location on the stack.

Clarity

• Clear, concise, accurate!

• Never give an incomplete statement of what the

reader has to do.

• Too much detail is better than too little.

• KISS

Keep it Simple and “Straight” to the point

• Simple: avoid compound sentences

“Reduction through successive refinement

is the only path to simplicity.”

22

designing the obvious

a common sense approach to web application design

robert hoekman, jr

Search

23

Why Controlled English?

Controlled English:

• Standardizing word usage leads to improved customer

acceptance/understanding.

• For non-English speakers, documents are easier to

understand.

• Lower translation costs.

• When something is first named, use only that name in

subsequent references to that something.

Do not add adjectives

24

Sentence Length is Important

• Use short, simple sentences.

• Keep length between 13 and 21 words.

• Read and revise… removing unnecessary words.

• Example

You can use TM-BASIC to check that a value entered is within a certain

range, to compare data against a value in another data variable, to

perform check-digit calculations, or to perform other arithmetic and

logical operations.

You can use TM-BASIC to:

• Check that a value entered is within a certain range

• Compare data against a value in another data variable

• Perform check-digit calculations

• Perform other arithmetic and logical operations

25

Pompous Style Redundancy and Padding

The result of:

Unclear thinking

Trying to impress

The desire to produce a large volume of work

Unwillingness to rewrite!!!

Example:

Due to the upcoming project submission to support the system upgrade as well as the introduction of the new products, the need is becoming eminent to identify all capital requirements of this process. Your input is important to the resolution of this issue.

versus

Please supply your capital requirements for support of future system

upgrades and introduction of the new products.

26

Using Numbers

• Write all numbers between zero and twenty as one

word.

• Write numbers thirty, forty, fifty, sixty, seventy,

eighty, and ninety as one word.

• Use hyphens to separate tens and units of numbers

like twenty-one.

• Write numbers above ninety-nine as Arabic

numbers (for example, 110).

• Never split a number across two lines.

27

Highlighting and Capitalization

Highlighting text:

• Never use underlining for emphasis (difficult to read)

• Bold for main section headings, subsection headings, figure

and table titles, emphasis, commands, file and directory

names

• Italics for references to other manuals, symbolic names,

variables in command syntax, long pieces of user input

Capitalization

- Chapter & appendix titles; Section headings

- Figure and table names

- Acronyms

- Entries in a glossary

28

more on Capitalization

Leading capital letter

• Subsection headings

• References to sections in text

• All heading entries in Table of Contents

• Main entries in an index

• Names of screen fields and menu items

29

Colloquialisms and Commands

• Colloquialisms (informal, regional), slang and

humor… don’t!!!

• What about use of (must and should) as opposed to

(can and may)?

Must means the action is required.

Should means that it is advisable.

Can implies capability.

May is vague, interpreted as meaning permissive / possible.

Humor

• The purpose of technical writing is

communication… not entertainment

• What may appear amusing to one reader may

prove incomprehensible to a second, and offensive

to a third

• Negatively impacts credibility

• Reflects on the assumed seriousness (that is, the.

professionalism) of those that did the work

• At best… read for the first time, humorous

… read for the nth time, not

30

31

He or She?

• Address your reader directly to avoid use of he or she.

• Where you think you need to make a choice, rewrite!

Examples:

If this happens, tell your administrator. He will have to reset your

password before you can log-in again.

If this happens, ask the system administrator to reset the password

and log-in again.

Change the workstation database to include the new workstation,

and ask him to log-in again.

Change the workstation database to include the new workstation,

and ask the user to log-in again.

32

Punctuation

Ellipses …

– Indicates something is missing from a quotation

– Indicates section of text has been omitted

Colon :

– Precedes a list

– Used when connected to the ideas “namely:”, “as follows:”,

“because:”, (even if these phrases are not used but can be

implied)

Semicolon ; – Used to separate two clauses which are closely connected.

– Example:

Secretarial is the adjective corresponding to secretary;

secretariat is the official … establishment of a secretary.

33

More Punctuation Advice

• Parentheses

Used to add a short remark without interrupting the flow of

the sentence.

“The network addresses (which are specified during

installation) cannot be changed.”

Note.

Sometimes hyphens - sort of like this - are used instead.

• Quotation marks (used for genuine quotations)

Use double quotation marks to enclose a quote

Use single quotation marks for quotations within a

quotation (She said “Did you know he said ‘ … ’ ”)

Point of View

1st person singular I write

1st person plural we write

2nd person singular you write

2nd person plural you write

3rd person singular he, she, one – writes

3rd person plural they wrote (the team wrote)

34