Managing in an XML environment

Managing in an XML
environment

Sarah O’Keefe, Scriptorium Publishing

background image
ﬂickr: 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.
ﬂickr: thelastminute

It’s about what happens
after the transition to XML.
ﬂickr: soschilds

Technical communication
is evolving.
ﬂickr: leafbug

Artisan to manufacturer
❖ Replace inefﬁcient processes
❖ Automate formatting
❖ Increase speed of delivery
❖ Reduce quality of formatting?
❖ Reduce total cost of creating work
product


XML is the foundation
❖ Signiﬁcant 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.
ﬂickr: rtpeat

The unpleasant reality
❖ Automation makes content production
less expensive.
❖ “Lovingly handcrafted” documentation
can be more attractive. It will deﬁnitely
be more expensive.


Traditional quality
measurement: appearance
❖ Attractive HTML pages
❖ Copyﬁtting
❖ 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 copyﬁtting.
❖ 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.
ﬂickr: groundzero

Transparency factors
❖ No hiding behind formatting tasks
❖ Easy to review content; nightly builds,
can see progress
❖ Lots and lots of metrics available


A ﬂood 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
❖ Signiﬁcant 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, ﬁndable, discoverable


High-quality content
❖ Writing: clear, concise, audience-
appropriate, accurate (!), up-to-date
❖ Formatting: Attractive, consistent,
well-executed
❖ Searchable, ﬁndable, 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.
ﬂickr: 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 efﬁciency.


Seductive metrics
ﬂickr: oriananash

Obvious = terrible
❖ Pages per hour
❖ Topics per day
❖ Percentage of reuse


Useful metrics
ﬂickr: 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
ﬂickr: law_keven

If it looks like a duck…

Quality + Usability + Accuracy + Completeness + Conciseness
Cost


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
Regulated Consumer
Metric documentation documentation
Quality 9 30
Usability 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)

P W P W

D
D
T T

Traditional XML

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
❖ okeefe@scriptorium.com
❖ Twitter: @sarahokeefe


Managing in an XML environment

Recommended

Recommended

More Related Content

Viewers also liked

Viewers also liked (14)

Similar to Managing in an XML environment

Similar to Managing in an XML environment (12)

More from Scriptorium Publishing

More from Scriptorium Publishing (20)

Recently uploaded

Recently uploaded (20)

Managing in an XML environment