Top strategies to embrace cost metrics

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?

Your turn

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.


Ragged-right or justified alignment?

Which alignment on the printed page is better: Ragged-right or justified? It seems that ragged-right is preferable, at least in some circumstances.

Today, I’m re-posting a piece that I first published on April 23, 2009, on the now defunct Content Wrangler site and then moved it to this blog as legacy material that was buried in the dark links of history…

I’m revisiting that post for two reasons: To my surprise, this has been one of my most popular posts in terms of search queries, so apparently this is an interesting topic. And I’ve discovered an additional argument with a twist that was new to me…

But first, let’s rewind…

Last year, I wrote:

How do you argue for the preference of ragged-right over justified alignment in print? Searching the web, I soon came across pages which mentioned research, but it was harder to actually find it.

  • The National Center on Educational Outcomes put out the NCEO Technical Report 37 which summarizes several arguments and references on the topic in “Table 3. Characteristics of Legible Type”, see the entry on “Justification”. Among them are:
    • Margaret Gregory’s and E. C. Poulton’s article “Even versus Uneven Right-hand Margins and the Rate of Comprehension in Reading”, Ergonomics, Volume 13, Issue 4, July 1970, pages 427-434. From the abstract: “… made no difference for good readers, but for the poorer readers the justified style resulted in a significantly worse performance.”
    • Steven Muncer, et al’s article “Right is Wrong: an examination of the effect of right justification on reading”, British Journal of Educational Technology, Volume 17, Issue 1, January 1986, pages 5-10. From the abstract: “… with reading material presented in right-justified format and in ‘ragged’ uneven line format, subjects performed significantly worse on right-justified material.”
    • David R. Thompson’s paper “Reading Print Media: The Effects of Justification and Column Rule on Memory”, paper presented at the Southwest Symposium, Southwest Education Council for Journalism and Mass Communication (Corpus Christi, TX, October 6-7, 1991). From the abstract: “… best score for recall was recorded in the flush left/jagged right.”
  • The UK government agency RNIB’s “Clear print guidelines” on designing printed information that is accessible to people with sight problems: “… avoid justified text as the uneven word spacing can make reading more difficult.”
  • The SEC’s “Plain English Handbook: How to create clear SEC disclosure documents” (PDF), see p. 50: “… spacing between words fluctuates from line to line, causing the eye to stop and constantly readjust.”
  • … and a thoughtful blog post by Ken Adams with an argument by Ellen Lupton, curator of contemporary design at Cooper-Hewitt National Design Museum, and author of “Thinking with Type: A Critical Guide for Designers, Writers, Editors, & Students”: “… subtle word-spacing and letter-spacing algorithms are needed to make justified text look ‘good’.”

Now I’ve found more arguments:

Karen Schriver’s book Dynamics in Document Design of 1997 is both comprehensive and excellent in explaining the motivation, the tools and the history of good document design. Be warned, however, that it deals almost exclusively with printed document design. Online design is the afterthought that takes up Appendix C, pages 506-517. (That detail right there tells you pretty much what kind of a book it is… 🙂 )

Schriver essentially argues that ragged-right vs. justified is the wrong question – imposed on us by software options, I want to add. According to Schriver, the real issue is word spacing.

Regular word spacing makes for faster reading and more accurate comprehension, in both ragged-right and justified text. Much of the software we use for writing gets word spacing in ragged-right alignment reasonably right without too much trouble. The problem with justified text is that it requires a sophisticated balance of letterspacing, word spacing and word hyphenation which much software apparently doesn’t get right automatically. Instead, it…

…creates a disturbing visual illusion known as “rivers” – paths running vertically through the text that connect the blank spaces between words on adjacent lines. (p. 270)

Here’s an illustration of rivers, from the Wikipedia article on Sentence spacing:

An example of the "river" effect in justified text

So, the bottom line is: If you have rivers in your text, consider ragged-right alignment to do your readers a favor – or invest extra time in spacing your lines nicely.

– If you know of any other arguments or sources that can help us tech writers with alignment and justification, please leave a comment!

Editing for tech writers

Tech writers don’t just write, we frequently also edit what our peers have written. As Tom Johnson recently tweeted:

Can’t decide if the technical editor role is dead or if technical writers have evolved into this role as their new default.  8:40 AM Apr 23rd

I wouldn’t call it a “default role” for us writers, though the “pervasive idea in companies that ‘anyone can write'” creates more demand for this role (paraphrased from another tweet by Tom three hours later).

I’ll gladly edit the work of another tech writer (and rely on their feedback in return), but I’m less likely to “clean this up by noon”: I’m not grammar boy, and if anyone can write, then anyone can also clean up behind himself… If and how I edit depends on the situation. But what do I mean by editing?

(And what do I mean by that photo? Nothing in particular. Except maybe: How do you illustrate editing? :-))

Editing 101

When it comes to technical editing I have three heroes: Robert Van Buren, Mary Fran Buehler, and Jean Weber. Robert and Mary put together the ultimate tech editing guide back in 1980, called Levels of Edit. An STC edition from 1992 is apparently out of print, but there’s still a summary and a PDF version out there. Their booklet is the most comprehensive and best structured guide to tech editing that I know. They distinguish nine (!) types of edit:

  1. Coordination
  2. Policy
  3. Integrity
  4. Screening
  5. Copy Clarification
  6. Format
  7. Mechanical Style
  8. Language
  9. Substantive

Depending on how thorough your task and how much time you have, you go through all or only some of the levels. In fact, they suggest five different levels of edit for different purposes of a document. Unless you create a production edit for a printing house or publisher, you will probably omit types 1 and 5. The others may be more or less relevant, depending on general policies and what kind of document you’re editing.

I find the nine types of edit so clear and well-structured, because they help me to stay consistent and focused in my editing:

  • When I do an integrity edit to make sure that the table of contents and index are up to date and show the correct page numbers and that all lists are numbered correctly, then I don’t want to worry about misapplied templates, line breaks, text justification and alignment.
  • When I do the mechanical style edit to assure compliance with the corporate style guide, I don’t want to haggle with Oxford commas and dangling participles.

Yes, it does mean that I go through the same document repeatedly, but I find that the additional time spent scrolling or turning pages is made up by the better focus.

Editing the work of others

You can edit your own work, but I don’t recommend it: I find I’m too entangled in my writing, constantly tempted to fix an odd phrase here, a less than perfect table there. If at all feasible, have your work edited by someone else, and edit the work of colleagues.

This is where my third hero Jean Weber comes in (no relation to me): Jean knows all about how to work with editors – or, if you’re an editor, how to work with people who write. She also pointed me towards Levels of Edit.

Jean is in Australia and, according to her website, retired from paid work. But she’s so generous, she shares her knowledge and experience. I found three articles especially helpful:

Your turn

How do you edit? How are your documents edited? Do you edit your own work or someone else’s? Feel free to share issues and insights in the comments.