Getting the Language Right

1. Getting the Language Right ITSW 1410 Presentation Media Software Instructor: Glenda H. Easter

2. Stylistic Guidelines forSoftware Documentation • Use Active Voice • Focus on Functionality • Write Simple • Build Parallel Structures • Use An Appropriate Tone Getting the Language Right, Chp. 10

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

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

5. 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 sound-alike 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

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

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

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

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

10. Problems of Style inSoftware 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

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

12. 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 possible. Getting the Language Right, Chp. 10

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

14. 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 the program. Getting the Language Right, Chp. 10

15. 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, humorous aside Getting the Language Right, Chp. 10

16. 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 background information. Getting the Language Right, Chp. 10

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

18. 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” which is flat. Getting the Language Right, Chp. 10