managing in an xml environment
TRANSCRIPT
![Page 1: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/1.jpg)
Managing in an XML environment
Sarah O’Keefe, Scriptorium Publishing
background imageflickr: thelastminute
Thursday, November 4, 2010
![Page 2: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/2.jpg)
❖ @sarahokeefe
❖ #tekom is the conference hashtag
Thursday, November 4, 2010
![Page 3: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/3.jpg)
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
![Page 4: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/4.jpg)
This session is not about XML implementation.
flickr: thelastminute
Thursday, November 4, 2010
![Page 5: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/5.jpg)
It’s about what happens after the transition to XML.
flickr: soschilds
Thursday, November 4, 2010
![Page 6: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/6.jpg)
Technical communication is evolving.
flickr: leafbug
Thursday, November 4, 2010
![Page 7: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/7.jpg)
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
![Page 8: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/8.jpg)
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
![Page 9: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/9.jpg)
Automation requires compromises.
flickr: rtpeat
Thursday, November 4, 2010
![Page 10: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/10.jpg)
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
![Page 11: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/11.jpg)
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
![Page 12: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/12.jpg)
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
![Page 13: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/13.jpg)
XML changes tech comm management.❖ Transparency
❖ Accountability
❖ Metrics
❖ Skill sets
❖ Collaboration
Thursday, November 4, 2010
![Page 14: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/14.jpg)
XML increases transparency.
flickr: groundzero
Thursday, November 4, 2010
![Page 15: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/15.jpg)
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
![Page 16: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/16.jpg)
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
![Page 17: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/17.jpg)
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
![Page 18: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/18.jpg)
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
![Page 19: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/19.jpg)
High-quality content
❖ Writing: clear, concise, audience-appropriate, accurate (!), up-to-date
❖ Formatting: Attractive, consistent, well-executed
❖ Searchable, findable, discoverable
Thursday, November 4, 2010
![Page 20: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/20.jpg)
Up-to-date content
❖ Faster publishing
❖ Incremental publishing
❖ More current content
Thursday, November 4, 2010
![Page 21: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/21.jpg)
Formatting
❖ Automation
❖ Cheaper than hand-coding each document
❖ Better consistency
Thursday, November 4, 2010
![Page 22: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/22.jpg)
Searchable
❖ Management must decide whether to make documents available to search engines
❖ Not a technical question
❖ A matter of policy
Thursday, November 4, 2010
![Page 23: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/23.jpg)
Findable
❖ Performs well in search results
❖ Affected by metadata
❖ Search engine optimization work
Thursday, November 4, 2010
![Page 24: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/24.jpg)
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
![Page 25: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/25.jpg)
Transparency means accountability.
flickr: leafbug
Thursday, November 4, 2010
![Page 26: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/26.jpg)
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
![Page 27: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/27.jpg)
Seductive metricsflickr: oriananash
Thursday, November 4, 2010
![Page 28: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/28.jpg)
Obvious = terrible
❖ Pages per hour
❖ Topics per day
❖ Percentage of reuse
Thursday, November 4, 2010
![Page 29: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/29.jpg)
Useful metrics
flickr: garryknight
Thursday, November 4, 2010
![Page 30: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/30.jpg)
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
![Page 31: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/31.jpg)
The writing quality equation: QUACK
flickr: law_keven
Thursday, November 4, 2010
![Page 32: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/32.jpg)
If it looks like a duck…
Quality + Usability + Accuracy + Completeness + ConcisenessCost
Thursday, November 4, 2010
![Page 33: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/33.jpg)
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
![Page 34: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/34.jpg)
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
![Page 35: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/35.jpg)
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
![Page 36: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/36.jpg)
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
![Page 37: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/37.jpg)
Conciseness
❖ Is the content verbose, repetitive, or redundant?
❖ Increases localization expenses
❖ Increases print expenses
❖ Causes comprehension problems
Thursday, November 4, 2010
![Page 38: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/38.jpg)
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
![Page 39: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/39.jpg)
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
![Page 40: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/40.jpg)
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
![Page 41: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/41.jpg)
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
![Page 42: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/42.jpg)
Thank you.
❖ Questions?
Thursday, November 4, 2010
![Page 43: Managing in an XML environment](https://reader036.vdocuments.site/reader036/viewer/2022070519/58f32f421a28abdb2d8b45af/html5/thumbnails/43.jpg)
Contact information
❖ Sarah O’Keefe
❖ www.scriptorium.com
❖ Twitter: @sarahokeefe
Thursday, November 4, 2010