Evaluating technical documents

Objectives  Evaluating Documents

Evaluating a Document  Is the document able to be understood by the reader?  Is the language/spelling/format/context clear and consistent?  Does it use active voice?  Is the language appropriate?  Are steps, lists, tables and bullets used?

Evaluating a Document  Is it task oriented?  Is the document accurate?  Is the document complete?  Is the level of information appropriate?  Is spelling and punctuation correct?  Is it gender neutral?  Does spacing/layout add to readability?

Understandability  Is the material understandable to the target audience?  First time users/experts?

Clarity & Consistency  Are the same terms and instructions used consistently? Click the left mouse buttonDouble click the mouse Type a name and hit enter Enter Enter a name and click enter Enter DocumentUser Manual DoDid

Active Voice  Makes the person the subject of the sentence and the action they perform, secondary. E.g. Mary walked the dog  Ensures that instructions are straightforward, simple and short Subject (Noun) Action (Verb)

Active Voice Active voice Anna got 100% for her exam. Passive voice A mark of 100% was scored by Anna. One exam score was 100%.

Active Voice Active voice Check the data for errors and press enter Passive voice After the data is typed, it should be checked for errors, then the enter key should be hit

Appropriate Language  Is the language long-winded?  Is jargon used / defined?

Steps, Lists, Tables, Bullets etc.  Numbered Steps, Lists, Tables and Bullets make a document easier to read

Steps, Lists, Tables, Bullets etc.  Use Bold: ○ Headings ○ Figures and table titles ○ Emphasis ○ Commands ○ File names  Use Italics: ○ References ○ Variables (in commands) ○ Long pieces of user input

Steps, Lists, Tables, Bullets etc.  Don’t Underline: ○ It makes things harder to read  Use full Capitalisation: ○ Titles ○ Figure and table titles ○ Acronyms ○ Logical operators (AND, OR, NOT)

Task Oriented  Is the manual related to the task or the concepts?

Accuracy  Correct Version  Correct screen, page, menu names used

Completeness  Is everything covered? ○ Alternative approaches ○ When and how often a task needs to be complete ○ What to do once finished

Level of Information  Is the reader overloaded with information?  Is the level of information appropriate for the user’s needs?

Punctuation Woman without her man is nothing Woman, without her man, is nothing. Woman! Without her, man is nothing.

Exercise Punctuate the following: Please review the following items jackets t shirts shoes and hats As of Monday night TV 3 will change its programming In an interview John stated that he was considering the proposal

Spelling  Their vs There  Programme vs Program  Practice vs Practise  Whether vs Weather  Make sure you check that the document is not set to American spelling (e.g. organization)

Graphics  Can provide a quick point of reference  Often easier, faster and clearer than words

Graphics Pros (if done right)Cons (if done poorly) SummariseConfuse Re-iterate, cement ideasTrivialise Reduce sizeIncrease size Add varietyClutter StimulateOver stimulate EntertainAnnoy

Graphics  Always label a table, graph or figure  Cite the label to identify the graphic (e.g. see figure 1.1) CEO MarketingFInanceHR FIGURE 1.1: Organisational Structure

Layout  Use white space  Check alignment  Consider sections

Gender Neutral  Pair of Pronouns He or she  Slash s/he  Use You  Use the plural ○ Users, readers, operators  Replace with a, an, the, who, which, that

Other Things to Think About  Presentation  Cover  Feel  Size