HeraTech

January 4, 2010

Agile Tenet #7 – Usable Doc as a Measure of Progress

Filed under: Uncategorized — heratech @ 8:35 pm
Tags: , , , ,

Seven Key Seventh in a series of posts examining the Twelve Principles of Agile Software and how each of these tenets can (or can’t) be applied or adapted to technical writing.

*****

Working software is the primary measure of progress.

Technical writers write documentation rather than software, so this is one of the tenets that needs to be slightly modified to apply to TWs. The question is, how do you define “working documentation” and whether or not the Agile technical writer is making progress?

We don’t want to use page count as a measure of progress. Lengthy docs often lack focus. Mark Twain said, “I didn’t have time to write a short letter, so I wrote a long one instead.” And Cicero, T.S. Eliot, Ernest Hemingway, Samuel Johnson, Blaise Pascal, George Bernard Shaw, and Voltaire have similar quotations about lengthy writing being an indication that they did not have time to do their best. Page counts are not a metric of good writing, in fact, if you localize, a low page count (and lower cost) is the goal.

Tightening up your writing can be as simple as changing “Click on the Save button” to “Click Save” which says essentially the same thing but takes less time to read (and if you’re localizing, saves you three words). But I’ve also seen people take brevity to extremes in an effort to reduce localizations costs. At one point during a cost cutting effort one of our executives found a company that promised to cut our word count by 40%. We sent them samples, but what came back was so spare as to be almost useless. If you’re only focused on word count or page count, you’ve lost sight of your users and meeting their needs.

Since tenet #9 is attention to Excellence, I believe that the measure of progress for a technical writer should be useful documentation. A couple of years ago I encountered the book Developing Quality Technical Information: A Handbook for Writers and Editors. I was so impressed with their definition of quality technical writing that I typed it up and posted it on the wall of my cube. Slightly paraphrased, their criteria are as follows:

Easy to use
Task Orientation Focused on helping users perform tasks related to their jobs.
Accuracy Free of mistakes and errors.
Completeness Includes all the necessary information, and only necessary information.
Easy to understand
Clarity Presents the information so that users understand it the first time.
Concreteness Includes appropriate examples, scenarios, specific language and graphics.
Style Appropriate writing conventions, words, and phrases.
Easy to find
Organization Arranging the parts in a way that makes sense to the user.
Retrievability Presentation that allows users to find information quickly and easily.
Visual Effectiveness Appropriate use of layout, illustrations, color, typography, etc.

I believe that one of the most important things you can do to make software documentation useful is to focus on the user’s task. Several years ago I took a community college course to learn how to use Photoshop. Our instructor chose the Photoshop Visual Quickstart Guide from PeachPit Press as our text. Both the course and the text were feature oriented rather than task oriented. As we worked our way through the many features of Photoshop I remember constantly wondering “But what would I use this for?” At the end of the semester we hadn’t covered what I suspect are the two most common corrections to photographs: removing red-eye and “correcting” skin blemishes. I could probably figure out which features to use, but it would have been helpful if the course and text had focused on common tasks.

Journalists seek to answer the Five Ws: Who? What? When? Where? Why? And How? I believe that useful documentation should seek to answer the same questions.

Useful documentation is the primary measure of progress for a technical writer.

Advertisements

1 Comment »

  1. […] Agile Tenet #7 – Usable Doc as a Measure of Progress (Julie Stickler) […]

    Pingback by Dew Drop – January 5, 2009 | Alvin Ashcraft's Morning Dew — January 6, 2010 @ 8:47 am | Reply


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Blog at WordPress.com.

%d bloggers like this: