Getting the Language Right

Getting the Language RightGetting the Language Right

ITSW 1410

Presentation Media Software

Instructor: Glenda H. Easter

Getting the Language Right, Chp. 10

2

Stylistic Guidelines forStylistic Guidelines forSoftware DocumentationSoftware Documentation

Use Active VoiceFocus on FunctionalityWrite SimpleBuild Parallel StructuresUse An Appropriate Tone


3

Guidelines for A User-Oriented Guidelines for A User-Oriented StyleStyle

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.


4

Guidelines for A User-Oriented Guidelines for A User-Oriented Style (Continued)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.”


5


3. Keep writing simple– Strive for simplicity in each sentence.– Break sentences into more than one sentence.– Find acceptable substitute phrasing so sound-

alike words don’t confuse the reader.– Try to write sentences that keep the subject and

verb together, as much as possible.


6


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.


7


4. Build parallel structures (Continued):– Types of Parallelism:

• . . . ing

• Noun First

• Parallel Sentences

• Imperative Voice


8


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


9


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


10

Problems of Style inProblems of Style inSoftware DocumentationSoftware Documentation

Too Many AcronymsConfusing SynonymsParagraph And Sentence LengthSystem OrientationInappropriate ToneAmbiguous Task NamesAmbiguous Step Instructions


11

Style Problems in Style Problems in Software Documentation (Continued)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.


12


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


13


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.


14

Style Problems in Style Problems in Software Documentation (Continued)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 the program.


15

Style Problems in Style Problems in Software Documentation (Continued)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, humorous aside


16

Style Problems in Style Problems in Software Documentation (Continued)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

background information.


17


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.


18

Style Problems in Style Problems in Software Documentation (Continued)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” which is flat.

Documents

Getting the Language Right