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

6.
Technical communication
is evolving.
flickr: leafbug
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

9.
Automation requires
compromises.
flickr: rtpeat
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

14.
XML increases transparency.
flickr: groundzero
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

19.
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

27.
Seductive metrics
flickr: oriananash
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