Transcript Getting the Language Right, Chapter 10

Getting the Language Right
ITSW 1410
Presentation Media Software
Instructor: Glenda H. Easter
Stylistic Guidelines for
Software Documentation
Use Active Voice
 Focus on Functionality
 Write Simple
 Build Parallel Structures
 Use An Appropriate Tone

Getting the Language Right, Chp. 10
2
Guidelines for A User-Oriented
Style
1. Focus on actions rather than functions
– Language makes the difference in the type of
understanding one manual provides over
another.
– Any documentation written to document
software should focus on action rather than on
functions.
Getting the Language Right, Chp. 10
3
Guidelines for A User-Oriented
Style (Continued)
2. Use the active voice
– A good rule for writing software
documentation:
• Subject at the beginning, a verb in the middle,
and a receiver at the end.
• Nouns clutter up things and verbs get things
done.
– Any forms of the verb “to be” (is, are, am, was,
were) should be left out.
– Focus on writing without a form of the verb “to
be.”
Getting the Language Right, Chp. 10
4
Guidelines for A User-Oriented
Style (Continued)
3. Keep writing simple
– Strive for simplicity in each sentence.
– Break sentences into more than one sentence.
– Find acceptable substitute phrasing so soundalike words don’t confuse the reader.
– Try to write sentences that keep the subject and
verb together, as much as possible.
Getting the Language Right, Chp. 10
5
Guidelines for A User-Oriented
Style (Continued)
4. Build parallel structures
– Parallel items acknowledge the similarities
between concepts and express that similarity in
matching grammatical structures.
– Headings that all end in "ing" follow the
principle of parallelism.
– Steps that all begin with a command verb
makes statements parallel.
Getting the Language Right, Chp. 10
6
Guidelines for A User-Oriented
Style (Continued)
4. Build parallel structures (Continued):
– Types of Parallelism:
•
•
•
•
. . . ing
Noun First
Parallel Sentences
Imperative Voice
Getting the Language Right, Chp. 10
7
Guidelines for A User-Oriented
Style (Continued)
5. Use operational overviews
– Users want a program and manuals that explain
how it operates and how it can make them more
efficient.
– Users read for meaning, and therefore you
should provide prose or paragraph passages
that provide a clear overview of concepts, as
well as straight procedures (steps).
Getting the Language Right, Chp. 10
8
Guidelines for A User-Oriented
Style (Continued)
5. Use operational overviews (Continued):
– There are three techniques writers emphasize
their explanations of abstract concepts:
• the theoretical (emphasizing the theories behind the
working of the program.)
• the technical (emphasizing the technical
functioning of the program.)
• the operational (emphasizing the application of the
program.)
Getting the Language Right, Chp. 10
9
Problems of Style in
Software Documentation
Too Many Acronyms
 Confusing Synonyms
 Paragraph And Sentence Length
 System Orientation
 Inappropriate Tone
 Ambiguous Task Names
 Ambiguous Step Instructions

Getting the Language Right, Chp. 10
10
Style Problems in
Software Documentation (Continued)

Too Many Acronyms and Abbreviations
– You can’t avoid acronyms, but try to use
them as little as possible.
– Every acronym or abbreviation should be
followed by its meaning, either in
parentheses or in the context of the
sentence.
Getting the Language Right, Chp. 10
11
Style Problems in
Software Documentation (Continued)

Confusing Synonyms
– Along with synonyms, you will find terms
that change from program to program.
Make sure your manual is clear as to the
use of the synonym for the program being
used.
– Synonyms have developed as ways to
describe overall tasks, but you should
always use them consistently and as
accurately as
Gettingpossible.
the Language Right, Chp. 10
12
Style Problems in
Software Documentation (Continued)

Paragraph And Sentence Length
– Paragraphs should focus on explanations,
not performance, and not on steps telling
the reader what to do.
– Paragraphs work best when they support a
simple concept.
– They help explain what happens after a
step, and they should be read was quickly
and easily as possible.
– Think in terms of lists and chunks of no
more than three sentences.
Getting the Language Right, Chp. 10
13
Style Problems in
Software Documentation (Continued)

System Orientation (Emphasizing the
Computer instead of the Program)
– Computerized work involves three
components:
• the user, the program, and the computer
– Users interact with the program not the
computer.
– Do not describe the actions of the
program to those of the computer.
– The computer
follows
the
instructions
of
Getting the Language Right, Chp. 10
14
the program.
Style Problems in
Software Documentation (Continued)

Inappropriate Tone
– Software documentation should sound
conversational, not too formal.
– Speaking in an informal tone puts the user
at ease.
– You can incorporate the following
characteristics into your style to give your
materials an informal tone:
• use contractions, reference to other users,
the Language Right, Chp. 10
humorousGetting
aside
15
Style Problems in
Software Documentation (Continued)

Inappropriate Tone
– When to Use Humor:
• Humor does not work in support sections such
as reference and appendices.
• Experienced users value accuracy over a more
intimate style when it relates to reference
sections.
• Never use in reference documentation.
• Seldom use it in procedures.
• Sometimes it is okay to use in tutorials and
Getting the Language Right, Chp. 10
16
background
information.
Style Problems in
Software Documentation (Continued)

Ambiguous Task Names
– Task-oriented documentation should name
tasks clearly.
– Try to make task names into headings or
short sentences that predicate the user’s
action.
– The name of the task should appear
frequently in the text of the manual.
Getting the Language Right, Chp. 10
17
Style Problems in
Software Documentation (Continued)

Ambiguous Step Instructions
– Articulate the action element of a step very
carefully.
– Examine your steps to make sure they
contain a clearly stated action, using an
imperative form of the verb.
– Don’t omit articles.
• Leaving out articles such as “the,” “an,” and
“a” promotes a “Telegram Style of Writing”
Getting the Language Right, Chp. 10
which is flat.
18