Moving to a structured writing environment can change the metrics of documentation. That’s one of the lessons I learned in a great webinar by Scriptorium‘s Sarah O’Keefe about “Managing in an XML environment”.
If you’ve missed it, check out the 45-minute recording/slideshow on their website. You’ll find it very interesting, if you’re wondering what it will be like to create and maintain documentation, once you have implemented XML. I’ll summarize a few aspects that I found interesting and comment on them.
XML increases transparency
Creating documentation in an XML environment increases the transparency in writing documentation, for better or worse. Tech writers’ work in XML is more visible earlier in the process: Without XML, a writer may deliver a print-ready PDF after months. With XML, she might check in topics every day for a nightly build.
Just as content gets chunked from books to topics, so progress gets chunked from weeks and months to hours and days. What can be measured often will get measured, so Sarah warns: Beware of seductive metrics. Measuring pages per day, for example, is silly: It will increase page count, but not necessarily the quality or the effectiveness of the documentation.
Strategy #1: Learn to QUACK
Measure something useful instead. Sarah suggests the QUACK quotient:
(quality + usability + accuracy + completeness + “konciseness”) / cost
Sarah goes on to define each of the five “QUACK” factors in similar terms as Gretchen Hargis, et al. in Developing Quality Technical Information. For example, quality considers whether the documentation is well-written and well-structured. “Konciseness” (spelling follows acronym as form follows function) means to provide as little documentation as is necessary, but no less. This improves efficiency for users and localizers alike.
I think this approach is great for scenarios where you can’t get out of cost metrics. Using accepted quality criteria is definitely better than being held to junky metrics.
But I wonder how quantifiable the five dividends actually are: How accurate is a topic? “Very accurate”, if I’m lucky – but I wouldn’t know how to put a number on that… Also, each dividend should be weighted according to audience and industry, Sarah explains. For example, completeness of documentation is more important in regulated industries than video games. That doesn’t make the quantification any easier or less contested.
Strategy #2: Duck the cost
My own strategy requires even more leverage for tech writers than just pushing a new formula through to assess our work. So it probably doesn’t work for all tech writers.
The QUACK quotient takes for granted that documentation is a cost center. Of course, many managers share that view. But I wonder if we tech writers wouldn’t be better off, if we got out of that defensive corner altogether.
I think it helps us more in the long run to show how documentation contributes to the larger corporate processes of production and value added. So I suggest that it’s worth to argue along these lines:
- Turn transparency into cost attribution: Show how each topic’s cost can be counted towards the development cost of the feature or part that it describes, just like other stages in the production processes. It’s like applying total cost of ownership to your own products.
- Turn topic reuse into corporate efficiency and assets: Show how reused topics create extra value or reduce costs in other departments, for example, in training, customer services or marketing.
- Measure relative cost savings: Show how writing XML-based documentation is more efficient than the previous non-XML process, once you’ve overcome the initial hurdles.
Bonus link: Cost metrics white paper
If you’re into DITA or want to see how cost metrics for structured writing break down to actual numbers, check out Mark Lewis’ clear and thorough white paper “DITA Metrics: Cost Metrics“:
You’ve already concluded that moving to DITA will save you tons of time and money. But management says prove it. This paper helps you determine the cost portion of the ROI calculation. What are my costs now? What will my new costs be with DITA? And what is the difference—my savings?
What do you think is the best way to justify tech writing cost? What scenarios or strategies have you seen succeed or fail? Share your thoughts in the comments.