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

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

Technology

Managing in global environment

1 Part 4: Compressing XML Data Managing XML and Semistructured Data

Managing Uncertainty of XML Schema Matching

Managing Multiproject Environment, FINALgmp/docs/papers/Managing Multiproject Environ… · Title: Microsoft Word - Managing Multiproject Environment, FINAL.doc Author: Administrator

Managing XML and Semistructured Data

Managing Human-Environment Interactions

Managing in a Global Environment

Managing the Urban Environment

Chapter 3-Managing Global Environment

Hecate, Managing Authorization with RESTful XML

Managing XML Data Dan Suciu University of Washington

Managing XML and Semistructured Data Lecture : Indexes

SQL Server - Querying and Managing XML Data

Managing Technical Content in an Enterprise XML Authoring Environment

Managing technical communicators in an XML environment

Managing an XML warehouse in a P2P environmentManaging an XML warehouse in a P2P environment Serge Abiteboul INRIA and Xyleme Caise 2003 – S. Abiteboul 2 Outline • Introduction

Managing XML and Semistructured Data Lecture 17: Publishing XML Data From Relations Prof. Dan Suciu Spring 2001

Managing Descriptive Metadata with Open XML...For Now

Managing an XML warehouse in a P2P environment

Managing in a Media Environment