TCUK 2012, Leah Guren, Golden Rules Redux

1. The Golden Rules
Technical communication theory and
application
TCUK 2012 Leah Guren
Cow TC

2. Meet the Golden Rules.
 Why theory?
• tool agnostic
• works for all types of TC projects
• provides a practical methodology
 Why these particular elements (the Golden
Rules)?
• the most common and critical
• based on experience and research
 People read books, but they use documentation.

3. The TC is a translator.

4. #1: Paper is permanent.

5. Hight protein powder provides the correct balance of
amnio acids to supplement the vagetarian/vegan diet
or the of anyone who is lactose intolerant. Over 80%
protein suger freee no added salat.
Over 200 medical jouranls documented as effective in
fighting and prevent: cancer, heart
disease, diabetes, diarrhea and moor.
Monufachured: <company name>
numary drive sheffield England

6. <product name> supports pear-to-pear
networking based on pubic domain protocols.
5. Click Advanced to defile system parameters.

7. What are quality and usability?
 Quality is a measure of accuracy (absence of
errors):
• typos, spelling mistakes, punctuation mistakes
• incorrect data
 Usability is a measure of how easily a document
can be used:
• can users find the information?
• can they understand it and use it?
• remember: a doc may have no errors but still not be
usable!
 Good docs need quality and usability!

8. You must be an expert.
 As a professional writer, you are expected to
know this.
 You may not have access to an editor.
 If you never learned, invest the time ASAP:
• grammar (including all that annoying jargon)
• punctuation
• proper writing style for TC

9. Parsing depends on punctuation.
woman without her man is nothing
Woman without her man is nothing.
Woman: without her, man is nothing.
9

10. Review TC punctuation rules.
 Commas
• closed (aka serial or Oxford comma)
• nonrestrictive phrases
• after prepositional phrases
 Colons and semicolons
• colons introduce
• semicolons link independent clauses
• never allow a comma splice
 Apostrophes
• contractions are OK
• don’t use with acronym plurals

11. Review TC punctuation rules, cont.
 Quotation marks
• never quote product or feature names, interface
elements, or actions (typeset instead)
• use correct symbols (printers’ quotation marks, not
straight ASCII quotes)
 Dashes
• distinguish hyphens, en dashes, and em dashes
• be consistent with space usage
 Parentheses
• nested vs. stand-alone parentheticals
 Capitalization
• don’t capitalize things not labels or proper nouns

12. Punctuation can add tone.
Keep all files, including sample data, in the
same folder.
Keep all files (including sample data) in the
same folder.
Keep all files—including sample data—in the
same folder.

13. Review TC writing style rules.
 Active voice
 Simple present tense
 Short sentences
 Simple, direct language
 Factual and accurate
 Unambiguous (watch those modifiers!)
 No gender bias

14. Paper is permanent.
 It is your responsibility to proofread and edit
carefully.
 If the docs have sloppy mistakes and look
unprofessional, users don’t trust the info.
 If the docs are ambiguous, hard to understand, or
incomplete (poor usability), users turn to tech
support (costing your company more £ € $ ¥).
 Exercise 1: Proofread.

16. #2: Know your audience.

17. You need Administrative Privileges to
install the hub software.
.
.
.
3. To change the value, position the mouse
cursor over the username and click
(press once) with the right mouse button.

18. Know your audience.
 Map demographics.
 Consider technical and product knowledge.
 Make safe assumptions.
 Distinguish the user from the market.
 Identify special needs.
 Find ways to get this info:
• tap internal sources (marketing, tech support, etc.)
• get customer contact
 Create personas.
 Exercise 2: Identify audience problems.

19.  What’s the problem?
 Why?
 What is a better solution?

20. #3: Highlight hazards.

21. Cleaning the <product name> Fryer
Clean the unit before storing or, during frequent use,
every week.
1. Open the unit by turning the lock nuts to the horizontal
position.
2. Lift the basket from the unit and place on newspaper or
rags to drain...

22. CAUTION! INVISIBLE LASER RADIATION WHEN
OPEN. AVOID EXPOSURE TO BEAM.

23. Highlight hazards.
 Find hidden hazards through scenarios.
 Rank hazards by severity:
• Danger
• Warning or Caution
• Note
 Make hazard visually clear.
 Use a simple do/do not statement.
 Explain ramifications and work-arounds.
 Place hazards appropriately:
• not after
• not too far before

24. Sample Hazard
Note: The unit may reach high temperatures. Care should be
taken to avoid contact with internal elements until the unit has
achieved sufficient thermo-adjustment.
DO NOT open the unit for at least ten (10)
minutes. Allow the unit to cool down; high
internal temperatures may cause burns.
Caution
Exercise 3: Spot the hazards.

25.  What are the problems?
 How do you know?
 What are two possible ways of dealing with
step 3?

26. #4: Break it out.

27. Antihistimine Comparison
Allegra (Fexofenadine; Aventis) is prescription only.
Allegra D is basically Allegra plus a decongestant in a
combination tablet (Aventis). Clarinex (Desloratadine;
Schering-Plough) is prescription only. However, Claritin
(Loratidine; Schering-Plough) became available as an
over-the-counter drug in December of 2002. Claritin D is
Claritin with a decongestant in a combination tablet
(Schering-Plough).

28. First, sort the clothing by color and fabric weight. Next,
go through all garments carefully to empty pockets.
Also look for any loose buttons that may come off in
the wash. Then, make sure that you read the care
labels for washing instructions, especially for any new
garments that you haven’t already laundered. Now,
find any stains or heavily soiled areas (check collars,
cuffs, etc.) and pre-treat them according to the
instructions on the stain remover product. Then, start
the wash, making sure to use the right temperature for
the clothes. In general, light colors and sturdy fabrics
(such as cotton) can take hotter temperatures.

29. Break it out and provide structure.
 Users don’t read blocks of text!
 Provide structure in documents.
 Think visually.
 Think about the way people need information.
 Exercise 4: Add structure.

30. What would you recommend for:
 Two older friends who are real foodies
 An amateur photographer with a very limited
amount of vacation time
 Newlyweds (wife is a wheelchair athlete)
 A vegetarian adventure traveler

31. #5: Don’t write blind.

32. We are supplying a software patch which should
take care of your Registry corruption problem.
After you install the patch (copy the files to the
installation directory), reset access value to single
copy. Since you are running an old version
(Windows 95 with French support), change the
keyboard setting for the proper ASCII code page.
This is in the Control Panel. The next time you
run the software, you will see the new access
check-box in the Configuration dialog box. Use
this (default) with single copy settings.

33. Background Filter
If selected, background filtering is allowed.

34. Know what you’re writing.
 Never rely on second-hand information.
 See it, touch it, use it.
 If you can’t do it, you can’t explain it.
 Think and ask (open questions and scenarios):
what the client wants is not always what users
need .
 Exercise 5: Think and ask.

35. These should have made you suspicious:
 Why all the blah-blah in the beginning?
 Based on the audience, isn’t the hazard wrong?
 How can this end after 16 weeks?
 What are the blue weights? Included?
 Show the exercises. Why a print document? Is
this the best way to train people?
 What is the problem with cold water?

36. #6: Be consistent.

37. The flexible baseboard design will
accept Pentium processors operating at
75 MHz, 90MHz, 100 MHz, 120
MHz, 133 mhz, 150-Mhz, and 166 MHz.

38. Be consistent.
 Inconsistency is very stressful for the user.
 Decide how to refer to the product.
 Pick one technical term.
 Consider interface elements and actions.
 Don’t forget styles, fonts, and layout.
 Use a style guide.
 Exercise 6: Spot the inconsistencies.

39. Inconsistencies:
 Product name written several different ways
 Prereqs don’t list quantities for all
 Units of measurement mix imperial and metric
 Technical terms:
• spray watering, sprinkler delivery
• faucet, tap
• drip irrigation, tube irrigation

40. #7: Signpost!

41. 1. Complete the software installation before
installing the fax-modem card.
2. If the default jumper settings are not
appropriate, change them before installing the
card.
3. After installing the card, reboot the PC and run
Quickcnf.exe from the Dialer folder...

42. Signpost
 CLI: If it isn’t documented, it doesn’t exist.
 GUI: If it isn’t accessible, it isn’t documented.
 Never make users read material that isn’t
appropriate for them.
 Use layout and typography to indicate
relationships of elements.
 All parts of the documentation suite need to
be aware of each other.

43. #8: Don’t violate standards.

44. Attach the cable to the wide connection plug at the
back of the <product name> box.

45. Don’t violate (legitimate) standards.
 Recognize the difference between a legitimate
(de jure) standard and a bad de facto rule.
 Understand issues relating to:
• regulatory and compliance
• certification
• recommendations
• other legal issues
 Go to the source for certification and guideline
standards.
 Get in the loop.
 Exercise 7: Conduct a standards audit.

46.  What did you discover?
 Are you missing info?
 How can you resolve this?

47. #9: Contemplate before you illustrate.

48. 4. To determine the card version, refer to
the serial number printed on the main chip.

49. Contemplate before you illustrate.
 Consider when you must have graphics:
• non-text GUI elements
• physical parts and assembly
• orientation (perfuming the pig)
 You may not need all of it.
 You may not need it at all!
 Use appropriate graphic types.
 Use callouts or annotations to focus attention.
 Placed the graphic after concept.

50. inline graphic
of non-text
GUI element
annotated
screen grab

51. drawing with elements
labeled (text overlaid on
graphic)
Note: Avoid for
localization
strategy!

52. exploded
view
diagram

53. isometric view
diagram

54. drawing with callout
handles
Exercise 8: What is essential?

55.  Did you have an icon for the battery symbol?
 Did you use a cabinet or isometric view?
 Did you remember the annotations?

56. #10: Cut the fluff.

57. We have included a free registration card with
<product name> so that you can fill it out and
mail it back to us as quickly as possible (we’ve
even paid for the postage, you’ll note). We could
take up several precious minutes of your life
telling you why this is a good idea, but we won’t.

58. The potential for attendance at the aforementioned
conference is problematic in that it is difficult, if not
impossible, to anticipate to any degree of certainty the
number of persons who will participate until very close to
the actual target date. This being so, it is therefore
desirable that detailed planning be based on an
assumption of capacity seating at most sessions within
the event; that is, planning and prearranging should be
done so that all last-minute changes are downward
adjustments in nature.

59. Cut the fluff.
 Fluff is a serious usability problem.
 Watch out for these common fluff items:
• formal and pompous writing
• hidden strong verbs
• unnecessary passive voice
 Vague language is also fluff.
 Where possible, use telegraphic style.
 Think visually to reduce text.
 KISS!
 Exercise 9: Cut the fluff.

61. Conclusion and Discussion
 The Golden Rules:
• provide the analytical decision tree for all projects
• help you defend editorial choices
• support a user-centric approach to documentation
 Where do you go from here?
• consider new trends and technologies in terms of GR
usability
• don’t ever forget your TC role as “translator”


62. Thank you!
Leah Guren A butter
technical communication
approach to
training & consulting
TC…
tel: (+972) 54-485-3473
email: leah@cowtc.com
Skype: leah.guren
website: www.cowtc.com