June 2012

Agile, DITA, and User and Task Analysis

CIDMIconNewsletterBill Gearhart, Comtech Services, Inc.


At the recent CMS/DITA North America conference in San Diego, I hosted two Agile birds-of-a-feather lunches to discuss how Agile and DITA can work together. The level of interest and energy along with the passionate discussions surpassed any previous lunches I’d hosted. The most in-depth of these discussions dealt with how best to integrate into a sprint (a short, usually 2-week product development cycle).

The majority of attendees felt that default tactic for integrating into a sprint—creating documentation that described how to use the code written in the sprint—was inadequate in giving the big picture and in setting context for customers. What I found interesting is the problem demonstrated by this approach—documenting the features from a limited, stand-alone perspective rather than writing for the user’s application of them in a complete scenario—is a problem that is not unique to Agile, but seems to be exacerbated by the time pressure of the sprints. What I found even more interesting is the paradox that Agile is meant to help teams focus on customer goals and capabilities. Why, then, were teams spending so much energy down in the weeds at odds with the very principles Agile was meant to support?

Agile teams often struggle with integrating information development effectively, even when the desire is there and the writers are seen as an equal part of the team. Resource constraints and too little participation in defining the product backlog frequently make it difficult for some writers to focus on the goals of the customer. Other writers lack the customer-domain knowledge needed to easily define the content that’s appropriate for the targeted audience. And even if the writing teams overcome those hurdles, the time constraints for delivering within a sprint often make goal-based writing difficult. The resulting easy way out is to “document the sprint,” resulting in the fundamental problem of documenting features (Agile work tasks, or “small, partial” stories) rather than the application of those features (full stories and epics).

For example, according to most Agile philosophies, all stories must be able to be completed within a sprint AND must add value to a customer. Those stories that can’t be completed in a sprint must be broken down into something that can be completed within a sprint. In my experience, teams under pressure often use such a breakdown as a cop-out, even if it’s an unconscious cop-out, to deliver features that are removed from direct customer benefit, and thus are difficult to document from a User and Task Analysis viewpoint. The documentation problems symptomatic of a cop-out are

  • Documenting the small stories without focusing on the value-add or application by the customer.
  • Documenting the trivial “button-clicking” that is feature-based rather than goal-based.
  • Focusing on system set-up rather than goal-based information. Often, this is symptomatic of an Agile team that took the easy way out—delivering code quickly while saddling the customer with decisions on how to manipulate the product to work properly in their environment.

It doesn’t have to be that way. From a DITA and User and Task Analysis perspective, Agile works quite nicely. But to take best advantage of Agile, writers must be involved at the epic and story level. Further, they must have the knowledge of the customers’ domain and the experience level of their targeted audience—ideally with direct contact with representative customers and the Agile Product Owner, just like the rest of the Agile team—to make appropriate judgments on the content needed. Writers also must have the ability to quickly break down the stories into a
work task list and estimate the time they need to develop content that is truly valuable.

After securing those prerequisites, an Agile writer’s tasks are straightforward, but not easy. Writers can use standard User and Task Analysis and Minimalism methodologies to develop their content, leveraging much of the work done by the Agile team as a whole and fitting neatly into the Agile philosophy. Combined with a DITA information model, writers can move quickly to address the highest priority customer needs.

For example, User and Task Analysis begins with identifying customer goals. In Agile, those goals have been defined in the form of the epics which are prioritized by the Product Owner. The next step is to identify the tasks that customers must perform to meet those goals. Again, these tasks map directly with Agile stories which have also been prioritized within the epics. Stories are the starting point for building task topics in DITA. Using the principles of Minimalism, the questions that writers should ask are: Is this task necessary for meeting a customer goal? Does the bulk of the targeted customer segment already know how to perform this task? What concepts and reference information must a customer know to perform this task? Does the bulk of the targeted customer segment already know those concepts and reference information? Is the task made up of multiple smaller tasks, or are there associated pre-requisite tasks?

Such an approach allows the writer to quickly build a prioritized work list of topics associated directly with the stories and one level removed from the epics or customer goals that the stories support. That work list can be prioritized with the Agile team and Product Owner if necessary, freeing the writer from unreasonable expectations while allowing focus on the highest value content for the customer. The challenge in this approach is to work with the other Agile team members to determine the appropriate number of topics that can be effectively covered in a sprint and satisfy a story. The team must be rigid in its prioritization, and writers must be willing to give up old notions of “completeness” and spend their efforts only on the topics that will have the greatest impact.

By using the approach of aligning Agile, User and Task Analysis, and DITA, disciplined writers and Agile teams can deliver the most useful content at the epic and story level, linking all of their work to customer capability, which is the whole point of Agile. CIDMIconNewsletter


Bill Gearhart

Comtech Services, Inc.

Prior to working with Comtech, Bill spent 15 years in the enterprise software industry, most recently as a director of operations for BMC Software, Inc. After starting his career as an information developer at a variety of manufacturing and consulting companies, Bill held several management positions in information development, usability, software engineering, project management, and support services.