English is not the language of habitual use for all technical authors writing in English. Similarly, users of English-language software products may not have first-language proficiency in the language. This presentation looks at strategies for ensuring the quality of technical documentation in a global IT environment.
2. Who We Are
I. Veronica Broughton-Shaw
• Managing Director, I.V. Solutions Ltd
Rowan Shaw
• Technical Communications Director,
I.V. Solutions Ltd
• Trainer, course designer, recruitment specialist,
technical author, editor
Tracie Misiewicz
• Marketing, public relations
3. Introduction
• Scenario 1: Authors without first-language English
• Scenario 2: Users without first-language English
• Assumption: Quality matters! Aim: high-quality product documentation
Some characteristics of high-quality product documentation:
Relevant for the target group(s), Accurate, precise, and specific
task-oriented
Logically structured, easy to Clearly formulated, grammatically
navigate, and easy on the eye correct
Complete (appropriate level of Consistent (style and terminology)
detail)
• Critical factor: Cost – Quality
can be expensive!
4. Recruiting Technical Authors
• What level of English do you/does your management expect?
e.g. Common European Framework of Reference for Languages
• What skills are not negotiable?
• Selection procedure:
• Include experts from the country/location
• Online language test: grammar, punctuation
• Written test
• Interview(s)
5. Break-Out Session 1: Analyse Sample Test
Purpose of a Documentation Test
• What information about a candidate would you expect a documentation test to
provide?
• Would you use an identical test:
• For all locations?
• For candidates with/without first-language English?
• Would you be focusing on different things when marking tests submitted by
candidates with/without first-language English?
Sample Test
• What do you think each part of the sample test is trying to test?
(skills/competencies)
• Which parts of the sample test would give you most insight into the skills of the
candidates without first-language English?
6. Break-Out Session 1: Analyse Sample Test
Part Mainly Tests: Does Not/Tests to a Lesser
Extent:
Picture • Grammar and fluency of • Structuring skills
expression • Writing for a specific target group
• Editing skills
Composition • Writing for a specific • Editing skills
target group
• Structuring skills
• Grammar, fluency of
expression
Editing • Editing skills • Structuring skills
Questions • Grammar and fluency of • Structuring skills.
expression • Editing skills
7. Training: What Can You Teach?
Teachable More Difficult to Teach
Many grammar points: Some more difficult grammar points:
• Use of articles • Prepositions
• Tense and aspect
• Count nouns versus noncount
nouns
Structuring of: • Organized approach to work
• Lists • Logical thought processes
• Tables
Main differences between American Many style points:
English and British English • Using modifiers correctly
• Avoiding mixed constructions
• Capitalization Register and tone
• Punctuation
Teaching methods: e-learning units followed up by quality circles
8. Users Without First-Language English
• Users may not have a high standard of English:
• Limited vocabulary: words with multiple meanings can represent a problem
“Reading is hard; writing is harder.”
“Reading is difficult; writing is more difficult than reading.” (The Elements of
International English Style”, Edmond H. Weiss
• Their language may have a different alphabet: reading is a burden (example of
Arabic and Hindi)
• Users may be familiar with a different regional variation of English.
• Cultural differences(?)
• Focus: Removing burdens! Texts must be “unusually simple,
unambiguous, and literal” (Edmond H. Weiss)
9. Removing Burdens: Global English
• Use common words and expressions
• Eliminate ambiguities (e.g. misplaced modifiers)
• Avoid complicated or unusual grammatical constructions
• Do not use figurative language
• Eliminate unnecessary inconsistencies
• Make sentence structure more explicit (syntactic cues).
Examples of rules for using syntactic cues:
Do not write in telegraphic style Enter appropriate password for key file access
and password for security key container if
installing new key.
Make sure that sentences are complete (both If the standard UI text does not fit the context,
syntactically and semantically). you can write your own.
Use an article before all nouns in a noun phrase. The documentation includes release notes, a
configuration guide and installation guide.
Use “that” with verbs such as “indicate”, “make As part of the handshake procedure, the client
sure”, “specify”, and “verify”. verifies the common name of the public
certificate exactly matches the hostname.
10. Examples of Tools and Activities That
Support Quality
Category Material/Activity
Materials and • House style guide
tools • Terminology database
• Style checker
• Spellchecker, readability checker
Editing • Copy editing
• Language editing
• Developmental editing
• Peer editing, quality circles
Testing and • Testing by target group
validating • Testing by SMEs
• Quality check (editors and tool-supported) to define training needs, etc.
Training • Classroom training (including virtual sessions)
• E-learning sessions
11. Which Quality Aspects Can You
Make Part of the Process?
• Provide house standards:
• Style guide (own guide or standard guide
such as Microsoft Manual of Style or
The IBM Style Guide plus company-specific
additions)
• Terminology database
• Global English
• Use quality-checking software:
• Acrolinx, Stylewriter, or similar tool
• Run quality circles
• Perform strategic quality checks
on documentation
12. Quality Check: A Strategic Approach
Check
documentation
• Check documentation for quality of: using defined
criteria
• Structure and content (editor)
• Grammar and style (editor, tool) Recheck Analyse results,
(or check other e.g. determine
• Spelling and punctuation (tool) documentation quality measures
by same author(s)) (such as training
• Formatting and presentation (editor)
needs)
• Analyse the results and take measures:
• Missing points style guide
Carry out quality
• Missing rules language-checking tool measures
• Identify training needs, design and deliver training
• Feed back results (team meetings, quality circles, training measures)
14. Break-Out Session 2: Quality Check
• Structure and Language check: Full Reduced Key
Criteria Criteria
Check text 1 using all criteria.
Structure and STR
content
• Language check:
Check text 2 using reduced criteria. Grammar X G
• Global English check:
Style X STY
Check text 2 using Global English
Spelling X SP
criterion.
Punctuation X P
Consider which parts of the validation
Formatting F
you can automate. and
presentation
• Consider what the action items are:
Global X GL
• Serious errors, errors that English
recur -> training needs?
15. Conclusions
• If you are recruiting technical authors without first-language English:
• Be clear about which skills/competencies are non-negotiable: What can you
teach? What are the cost factors?
• If your users do not have first-language English, make sure your writers and editors
are trained in Global English principles.
• In all cases: Make sure the writing process is supported by:
• Style guides
• Language-checking software (as part of writing process)
• Strategic quality checks (by editors, tool-supported).
Feed back the results of checks (training,
quality circles, additions to style guides)
16. Any Questions?
I.V. Solutions Ltd
The Old Methodist Chapel
High Street
Broughton
SO20 8AD
United Kingdom
+44 (0)1794 301593 (t)
+44 (0)1794 330070 (f)
+44 (0)7711 077045 (m)
17. Bibliography
• The Global English Style Guide: Writing Clear, Translatable Documentation for a Global Market, John R.
Kohl, 2008, SAS Institute Inc., ISBN 978-1-59994-657-3
• The Elements of International English Style: a guide to writing English correspondence, reports, technical
documents, and internet pages for a global audience, Edmond H. Weiss, 2005, M.E. Sharpe Inc, ISBN 0-
7656-1572-X
• Microsoft Manual of Style, 2012, Microsoft Press, ISBN 978-0735648715
• The IBM Style Guide: Conventions for Writers and Editors, 2011, IBM Press, ISBN 978-0132101301
• Technical Writing in China, Ivan Walsh: http://idratherbewriting.com/2011/06/15/technical-writing-in-china/
• The Teacher„s Grammar of English: A Course Book and Reference Guide, Ron Cowan, 2008, Cambridge
University Press, ISBN 978-0-521-80973-3
• Wikipedia article about the Common European Framework of Reference for Languages:
http://en.wikipedia.org/wiki/Common_European_Framework_of_Reference_for_Languages
Art work by Heather Butler: http://heatherbutlerartist.blogspot.de/
19. Appendix B: Common European Framework
of Reference
The CEFR describes what a learner is supposed to be able to do in reading,
listening, speaking and writing at each level.(excerpt):
