Tag Archives: development

On The Fly (Part 2)

Great minds think alike! I wrote about the impact  on the impact of agile software development on documentation (see On The Fly) where I shared my experiences how the frequent (and often extensive) changes to product features make it difficult to create conventional documentation such as product manuals and online help within tight project deadlines. After that post, I came across The Agile Technical Writer and The Agile Technical Writer II by Susan Maddox. Based on her experiences working on agile projects. she came to the conclusion that, rather than her role as a technical writer being cut out of the loop, she finds it has become even more interesting, exciting, and valuable.  She said, “As a technical writer, my aim is to reduce other people’s work, by making the documentation as simple and useful as possible. It takes a lot of work to achieve that simplicity. But it’s awesome because it’s what I love doing.”

I couldn’t agree with her more wholeheartedly. I urge you to read Susan’s posts to get a another insider’s perspective on the impact that agile development is having on how products and services are documented.

On the Fly

The original premise when I started this blog was to discuss how Web 2.0 technologies and open source software are changing the way that products and services are documented. Document collaboration among a community of authors (and not just a single team of writers) is becoming the norm with open source software projects such as Glassfish and Ruby on Rails using blogs and wikis for discussions and draft reviews. The influence of document collaboration will become more pervasive as (once) proprietary products such as databases and operating systems incorporate open source components (such as MySQL Enterprise and Red Hat Enterprise Linux).

An even more fundamental change than the increased use of document collaboration tools is the way that software products and services are being developed. As customer requirements demand more flexibility and quicker response in planning and implementation, companies are adopting agile development processes that focus more on working software than formal detailed specifications. The foundation of agile development are principles where software is planned, implemented, and tested “on the fly” so that project teams work closely with customers as requirements change, rather than treat change as an impediment to the development process. For more information, a presentation on agile development (in particular the Scrum methodology) is available here from the Scrum Alliance.

The impact on conventional product documentation (from user guides to online help) is potentially huge when a project team adopts an agile development process. No longer can writers use formal specifications as a negotiating point with project teams to determine the number, scope, or schedule of document deliverables. Likewise, writers can no longer rely on formal specifications to provide the gist of the information that will be fleshed out during the draft development and review cycle. Instead, the de-emphasis on formal specifications in agile development means that writers must be able to install and configure the software from working prototypes to the final version in order to create the needed task, reference, and conceptual documentation.

Scott W. Ambler wrote an excellent article detailing the documentation issues for agile development. Some of the insights that he shares are:

  • The fundamental issue is communication among team members, not formal documentation.
  • Write documentation if that’s the best way to achieve relevant goals, but there are often better ways to achieve these goals than static documentation (such as an online help system that focuses only on a single product release or version).
  • Document information that is stable (not speculative).
  • Seek (then act) on feedback on a regular basis throughout the document draft and review process.

Because of the iterative nature of agile development, Ambler notes that a best practice should be to wait until the information has stabilized before you capture it in documentation. It is risky to capture speculative information, such as requirements or design details, early in the lifecycle because those details are likely to change.

To give you some idea of the current (and likely) demands for someone wishing to create documentation on an agile project, you can look at a wiki article intended to describe the administration console for an open source project. As with the rigor of agile development, the administration console underwent significant UI changes between the November 2008 community milestone build to the current Beta build in January 2009 — requiring a total of 38 draft revisions to the original wiki article posted in November (and likewise supporting the decision that a conventional online help system for the console was too risky at that stage in the development). To track all those changes, myself and another writer became part SME (knowing what the software is supposed to do), part system administrator (install & configure software), part QA engineer (figure out what the software actually does and doesn’t do) before we can even devote time to the task of actually writing.

This effectively means that writers are no longer insulated from the software development and QA testing processes with a unique process just for product documentation. Writers will increasingly be asked (if not required) to participate as peers on the project team during agile software development, or else their jobs will (most likely) become redundant.