Getting the Language Right, Chapter 10

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 dont 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 cant 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 possible. Getting 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 the program. Getting the Language Right, Chp.

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

Recently Viewed Presentations

  • An update on kansas sensor based N recommendations

    An update on kansas sensor based N recommendations

    Sensor Based Results in Kansas *Drew Tucker and Dave Mengel. e-mail: [email protected] Oklahoma State University. Field & Research Service Unit. Chickasha, OK
  • Inborn Errors of Metabolism Emergencies in Neonates Joseph

    Inborn Errors of Metabolism Emergencies in Neonates Joseph

    Laboratory Evaluation Possibilities. Start with- Electrolytes, glucose, CBC, ammonia, urine for ketones, and lactic acid. Check the newborn screen. Plasma amino acids, Urine organic acids, Acyl carnitine profile, and free and total carnitine.
  • Friendship and Support

    Friendship and Support

    examples of support and friendship in school. Keep it up … What I do not like are people who . make others feel bad!! Consider… What do your friends see in you? Do you offer support to others? Do you...
  • Курс по уеб програмиране

    Курс по уеб програмиране

    Между двойни кавички може да има единични и обратно"Happy am I; from care I'm free!"'"Avast, ye lubbers!" roared the technician.'"45"'c'
  • Mink Dissection - Mr. Eroh

    Mink Dissection - Mr. Eroh

    Identify this muscle #23.How is the relative size of this muscle different in humans? Sartorius. Thin in a human (this muscle does not cover the entire ventral surface of the leg as in mink, but wraps laterally from the hip...
  • An Investigation of Available Metadata - UNSD

    An Investigation of Available Metadata - UNSD

    National Strategic Development Plan Update 2014-2018, which is a live document with includes set of indicators, including MDGs as key framework for monitoring & evaluation the progress. Sectoral Development Policies/Strategies (e.g. Education Strategic Plan, Health Sector Development Plan and Green...
  • Global workplace training - Online-Tutoring

    Global workplace training - Online-Tutoring

    Muslim culture is more dependent on non-verbal communication than they are on verbal communication. Muslims have a close physical relationship with friends, they hug, kiss and hold hands with the same gender. Staring, touching, holding hands or sometimes even speaking...
  • Health Systems Thinking International

    Health Systems Thinking International

    Professor Brian Dangerfield, University of Salford HEALTH SYSTEMS THINKING INTERNATIONAL LINKS BETWEEN URBAN PLANNING & HEALTH In cities there is a complex interplay between social, cultural, economic, technological & biophysical factors in generating demand for health care (www.healthycities.org.uk ; underpinned...