1. Managing in an XML
environment
Sarah O’Keefe, Scriptorium Publishing
background image
flickr: thelastminute
Thursday, November 4, 2010
2. Twitter
❖ @sarahokeefe
❖ #tekom is the conference hashtag
Thursday, November 4, 2010
3. About Sarah O’Keefe
❖ Founder and President, Scriptorium
Publishing, based in North Carolina, USA
❖ Content strategy for technical
communication
❖ Undergraduate degree in Comparative
Area Studies and German, Duke
University
Thursday, November 4, 2010
4. This session is not about
XML implementation.
flickr: thelastminute
Thursday, November 4, 2010
5. It’s about what happens
after the transition to XML.
flickr: soschilds
Thursday, November 4, 2010
7. Artisan to manufacturer
❖ Replace inefficient processes
❖ Automate formatting
❖ Increase speed of delivery
❖ Reduce quality of formatting?
❖ Reduce total cost of creating work
product
Thursday, November 4, 2010
8. XML is the foundation
❖ Significant change resistance
❖ Not everyone needs XML today
❖ With XML, you can integrate
documentation into product development
❖ No longer is documentation separate in
its own proprietary world
❖ Engineers understand XML
Thursday, November 4, 2010
10. The unpleasant reality
❖ Automation makes content production
less expensive.
❖ “Lovingly handcrafted” documentation
can be more attractive. It will definitely
be more expensive.
Thursday, November 4, 2010
11. Traditional quality
measurement: appearance
❖ Attractive HTML pages
❖ Copyfitting
❖ Production editing
❖ Line breaks
❖ Balanced headings
❖ Formatting tricks to make pages look nicer
Thursday, November 4, 2010
12. An inconvenient truth
❖ Your readers probably don’t notice
advanced production, like copyfitting.
❖ XML does not equal ugly.
❖ Poor implementation of XML does equal
ugly.
❖ Currently, the poor PDF implementations
seem to outnumber the good
implementations.
Thursday, November 4, 2010
13. XML changes tech comm
management.
❖ Transparency
❖ Accountability
❖ Metrics
❖ Skill sets
❖ Collaboration
Thursday, November 4, 2010
15. Transparency factors
❖ No hiding behind formatting tasks
❖ Easy to review content; nightly builds,
can see progress
❖ Lots and lots of metrics available
Thursday, November 4, 2010
16. A flood of data
❖ More data than we can reasonably
evaluate
❖ “Is this document a good document?”
❖ Transparency a threat to less skilled
writers
Thursday, November 4, 2010
17. The problem with data
❖ Easy to measure:
❖ Page count
❖ Hard to measure:
❖ Document quality
❖ Significant temptation to measure the
wrong things.
❖ Transparency is a double-edged sword.
Thursday, November 4, 2010
18. How do you measure
high-quality content?
❖ Writing: clear, concise, audience-
appropriate, accurate (!), up-to-date
❖ Formatting: Attractive, consistent,
well-executed
❖ Searchable, findable, discoverable
Thursday, November 4, 2010
20. Up-to-date content
❖ Faster publishing
❖ Incremental publishing
❖ More current content
Thursday, November 4, 2010
21. Formatting
❖ Automation
❖ Cheaper than hand-coding each
document
❖ Better consistency
Thursday, November 4, 2010
22. Searchable
❖ Management must decide whether to
make documents available to search
engines
❖ Not a technical question
❖ A matter of policy
Thursday, November 4, 2010
23. Findable
❖ Performs well in search results
❖ Affected by metadata
❖ Search engine optimization work
Thursday, November 4, 2010
24. Discoverable
❖ Content that has in-bound links from
related stuff
❖ Content that is found by browsing
❖ Affected by your site’s reputation (better
reputation = more links)
❖ Social media strategy
Thursday, November 4, 2010
25. Transparency means
accountability.
flickr: leafbug
Thursday, November 4, 2010
26. Accountability
❖ Formatting responsibilities eliminated
❖ Metrics can show average topic creation time
❖ Person A takes twice the time of Person B
❖ Person A’s topics are more expensive in
localization
❖ Does management choose good metrics?
❖ Must go beyond perceived efficiency.
Thursday, November 4, 2010
28. Obvious = terrible
❖ Pages per hour
❖ Topics per day
❖ Percentage of reuse
Thursday, November 4, 2010
29. Useful metrics
flickr: garryknight
Thursday, November 4, 2010
30. What are useful metrics?
❖ Usage numbers/web analytics
❖ Search patterns
❖ What information do people search for?
❖ Which searches are successful or
unsuccesful?
❖ How do you measure content quality?
Thursday, November 4, 2010
31. The writing quality
equation: QUACK
flickr: law_keven
Thursday, November 4, 2010
32. If it looks like a duck…
Quality + Usability + Accuracy + Completeness + Conciseness
Cost
Thursday, November 4, 2010
33. Quality
❖ Quality of content
❖ Grammar, mechanics, usage, reading
level (equivalent factors for visuals)
❖ More important for low literacy users,
non-native language users, and picky
users (language teachers!!)
❖ Less important for technical audiences?
Thursday, November 4, 2010
34. Usability
❖ Critical for products where motivation is
low—products that people choose to use
❖ How attractive is the content
presentation?
❖ How good is the navigation?
❖ Does the content use the appropriate
medium (text, video, graphics)?
Thursday, November 4, 2010
35. Accuracy
❖ Is the information correct?
❖ Extra-important for nuclear weapons
documentation and other products that
affect health and/or safety
❖ Less important for casual games
Thursday, November 4, 2010
36. Completeness
❖ Are all features described?
❖ Are there hidden, undocumented
features?
❖ Games might leave out features on
purpose
❖ Medical device documentation should
not leave out information
Thursday, November 4, 2010
37. Conciseness
❖ Is the content verbose, repetitive, or
redundant?
❖ Increases localization expenses
❖ Increases print expenses
❖ Causes comprehension problems
Thursday, November 4, 2010
38. Build your own QUACK
model
Regulated Consumer
Metric documentation documentation
Quality 9 30
Usability 10 30
Accuracy 40 10
Completeness 40 10
Conciseness 1 20
Total 100 100
Thursday, November 4, 2010
39. Writing in XML changes
the mix of skills needed.
Writing ability (W)
Tools (T)
Domain (D)
People skills (P)
P W P W
D
D
T T
Traditional XML
Thursday, November 4, 2010
40. The biggest hurdle:
Collaboration
❖ Shift to topic focus rather than
deliverable focus
❖ Looking for excuses to avoid reuse
❖ Need trust
❖ High-functionining team
Thursday, November 4, 2010
41. Final notes
❖ White paper version: scriptorium.com/
resources/white-papers/managing-
technical-communicators-in-an-xml-
environment
❖ scriptorium.com/resources for white
papers and webcast recordings
❖ scriptorium.com/events for upcoming
events
Thursday, November 4, 2010
42. Thank you.
❖ Questions?
Thursday, November 4, 2010
43. Contact information
❖ Sarah O’Keefe
❖ www.scriptorium.com
❖ okeefe@scriptorium.com
❖ Twitter: @sarahokeefe
Thursday, November 4, 2010