Managing in an XML environment

Managing in an XML environment

Sarah O’Keefe, Scriptorium Publishing

background imageflickr: thelastminute

Thursday, November 4, 2010

Twitter

❖ @sarahokeefe

❖ #tekom is the conference hashtag


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


This session is not about XML implementation.

flickr: thelastminute


It’s about what happens after the transition to XML.

flickr: soschilds


Technical communication is evolving.

flickr: leafbug


Artisan to manufacturer

❖ Replace inefficient processes

❖ Automate formatting

❖ Increase speed of delivery

❖ Reduce quality of formatting?

❖ Reduce total cost of creating work product


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


Automation requires compromises.

flickr: rtpeat


The unpleasant reality

❖ Automation makes content production less expensive.

❖ “Lovingly handcrafted” documentation can be more attractive. It will definitely be more expensive.


Traditional quality measurement: appearance❖ Attractive HTML pages

❖ Copyfitting

❖ Production editing

❖ Line breaks

❖ Balanced headings

❖ Formatting tricks to make pages look nicer


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.


XML changes tech comm management.❖ Transparency

❖ Accountability

❖ Metrics

❖ Skill sets

❖ Collaboration


XML increases transparency.

flickr: groundzero


Transparency factors

❖ No hiding behind formatting tasks

❖ Easy to review content; nightly builds, can see progress

❖ Lots and lots of metrics available


A flood of data

❖ More data than we can reasonably evaluate

❖ “Is this document a good document?”

❖ Transparency a threat to less skilled writers


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.


How do you measure high-quality content?❖ Writing: clear, concise, audience-

appropriate, accurate (!), up-to-date

❖ Formatting: Attractive, consistent, well-executed

❖ Searchable, findable, discoverable


High-quality content

❖ Writing: clear, concise, audience-appropriate, accurate (!), up-to-date

❖ Formatting: Attractive, consistent, well-executed

❖ Searchable, findable, discoverable


Up-to-date content

❖ Faster publishing

❖ Incremental publishing

❖ More current content


Formatting

❖ Automation

❖ Cheaper than hand-coding each document

❖ Better consistency


Searchable

❖ Management must decide whether to make documents available to search engines

❖ Not a technical question

❖ A matter of policy


Findable

❖ Performs well in search results

❖ Affected by metadata

❖ Search engine optimization work


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


Transparency means accountability.

flickr: leafbug


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.


Seductive metricsflickr: oriananash


Obvious = terrible

❖ Pages per hour

❖ Topics per day

❖ Percentage of reuse


Useful metrics

flickr: garryknight


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?


The writing quality equation: QUACK

flickr: law_keven


If it looks like a duck…

Quality + Usability + Accuracy + Completeness + ConcisenessCost


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?


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)?


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


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


Conciseness

❖ Is the content verbose, repetitive, or redundant?

❖ Increases localization expenses

❖ Increases print expenses

❖ Causes comprehension problems


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


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


The biggest hurdle: Collaboration❖ Shift to topic focus rather than

deliverable focus

❖ Looking for excuses to avoid reuse

❖ Need trust

❖ High-functionining team


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


Thank you.

❖ Questions?


Contact information

❖ Sarah O’Keefe

❖ www.scriptorium.com

❖ [email protected]

❖ Twitter: @sarahokeefe


http://www.scriptorium.com

http://www.scriptorium.com

mailto:[email protected]

mailto:[email protected]

Technology

Managing in an XML environment