Select Page

Ena Arel recently wrote a blog post about Agile Content Development and started a related discussion in the CIDM LinkedIn group. In her post, she asks if there is a conflict created when agile software development focuses on features instead of user tasks. Our good friend Larry Kunz at SDI commented that proper agile development starts with User Stories – which are inherently focused on user goals, and the tasks users perform with a product to accomplish those goals.

We agree with Larry – agile design should focus on user stories. At Jorsek we use an agile / continuous integration methodology for design and development our easyDITA software. We write User Stories, which cover sets of features that enable those stories – or “entire workflows” as Ena calls them. The User Stories identify users’ goals, and the tasks that users need to perform with the product to accomplish those goals.

Others have referred to this as a “scenario-based” information development approach. JoAnn Hackos wrote a comprehensive article on user scenarios in the March 2007 edition of Information Development News. Microsoft’s info dev team recently presented an excellent update on scenario-based information development at the 2012 CIDM Best Practices conference in September.

Regardless of what you call the approach, the key aspect is to organize agile design and development sprints around user stories, map those user stories to complete feature sets that accomplish user goals, and to in turn define the user tasks involved, and document those tasks.

In addition to using user stories to plan and organize our agile sprints, we are adopting a “documentation first” approach for information development that is intertwined with our agile methodology. It works like this:

  • We define the user tasks for each user story, and write preliminary documentation for them (in the form of DITA tasks). We write the preliminary tasks before we code (as part of the design process).
Explore Map Mock Up

Map Explorer Mock Up

  • Then we create wireframes/mock-ups of the UI. Together these form the design.

  • We review the design with our customers, prospective customers, and business partners to make sure it meets their requirements. We improve the design if needed.
  • We implement (code) the features.
  • We do usability testing and QA. To help with testing, the preliminary DITA tasks are published into our QA system and used as test scripts by our QA/usability team. This assures that the software works as documented, and that the documentation and software “match.”
  • After testing we evaluate if the design needs improvement, and if so we elaborate / update the task documentation and wireframes (redesigning the features, as it were). Then we implement the improvements and retest, and reevaluate.
  • When we’re satisfied that the user goals are met and usability goals are achieved, we freeze the UI design, capture the screens, insert them into the task documentation, and add the final “gloss” to the documentation. This gloss includes a final review and edit for our documentation standards, adding metadata for search on our documentation portal, semantically tagging the content (e.g. user controls in DITA), and adding any essential concept and reference topics to support the task.


Explore Map DITA Task

Explore Map DITA Task

  • We publish the documentation to our delivery portal simultaneously with the release of the software update.
  • We find that this User-story-based approach combined with “document-first” task-focused information development in DITA has the benefits of:
  • Improving the design of the software to assure users can achieve their goals
  • Improving the design of the documentation to assure it is aligned with user goals and supports their performance
  • Implementing the core principles of Minimalism in the documentation and the software user experience, improving the overall fit of the product to its purpose
  • Aligning our business and work processes for software design, development, testing/QA, and information development
  • Speeding time to market for software enhancements
  • “Sim-ship” of documentation with the product

Now that we are working this way, we can’t imagine returning to the process of designing and building the software and then writing the documentation. I personally can’t envision how we could do this without using DITA and our easyDITA collaboration tools – which form the secret sauce for integrating the content into the design, QA, product support, and dynamic content delivery processes.

Get a Demo