Upload
scriptorium-publishing
View
1.029
Download
0
Embed Size (px)
Citation preview
Managing in an XML environment
Sarah O’Keefe, Scriptorium Publishing
background imageflickr: thelastminute
Thursday, November 4, 2010
❖ @sarahokeefe
❖ #tekom is the conference hashtag
Thursday, November 4, 2010
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
This session is not about XML implementation.
flickr: thelastminute
Thursday, November 4, 2010
It’s about what happens after the transition to XML.
flickr: soschilds
Thursday, November 4, 2010
Technical communication is evolving.
flickr: leafbug
Thursday, November 4, 2010
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
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
Automation requires compromises.
flickr: rtpeat
Thursday, November 4, 2010
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
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
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
XML changes tech comm management.❖ Transparency
❖ Accountability
❖ Metrics
❖ Skill sets
❖ Collaboration
Thursday, November 4, 2010
XML increases transparency.
flickr: groundzero
Thursday, November 4, 2010
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
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
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
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
High-quality content
❖ Writing: clear, concise, audience-appropriate, accurate (!), up-to-date
❖ Formatting: Attractive, consistent, well-executed
❖ Searchable, findable, discoverable
Thursday, November 4, 2010
Up-to-date content
❖ Faster publishing
❖ Incremental publishing
❖ More current content
Thursday, November 4, 2010
Formatting
❖ Automation
❖ Cheaper than hand-coding each document
❖ Better consistency
Thursday, November 4, 2010
Searchable
❖ Management must decide whether to make documents available to search engines
❖ Not a technical question
❖ A matter of policy
Thursday, November 4, 2010
Findable
❖ Performs well in search results
❖ Affected by metadata
❖ Search engine optimization work
Thursday, November 4, 2010
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
Transparency means accountability.
flickr: leafbug
Thursday, November 4, 2010
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
Seductive metricsflickr: oriananash
Thursday, November 4, 2010
Obvious = terrible
❖ Pages per hour
❖ Topics per day
❖ Percentage of reuse
Thursday, November 4, 2010
Useful metrics
flickr: garryknight
Thursday, November 4, 2010
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
The writing quality equation: QUACK
flickr: law_keven
Thursday, November 4, 2010
If it looks like a duck…
Quality + Usability + Accuracy + Completeness + ConcisenessCost
Thursday, November 4, 2010
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
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
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
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
Conciseness
❖ Is the content verbose, repetitive, or redundant?
❖ Increases localization expenses
❖ Increases print expenses
❖ Causes comprehension problems
Thursday, November 4, 2010
Build your own QUACK model
MetricRegulated
documentationConsumer
documentation
Quality 9 30Usability 10 30
Accuracy 40 10
Completeness 40 10
Conciseness 1 20
Total 100 100
Thursday, November 4, 2010
Writing in XML changes the mix of skills needed.
Writing ability (W)Tools (T)Domain (D)People skills (P)
Traditional XML
W W
T T
DD
P P
Thursday, November 4, 2010
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
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
Thank you.
❖ Questions?
Thursday, November 4, 2010
Contact information
❖ Sarah O’Keefe
❖ www.scriptorium.com
❖ Twitter: @sarahokeefe
Thursday, November 4, 2010