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.


7 responses to “On the Fly

  1. I have added a page to my blog that lists the agile development articles that I referenced in this post, as well as interesting items from the Web:


    Let me know if it’s helpful, or if you have other feedback about agile development and documentation issues.

  2. Hallo Joseph

    Great post! I think your last paragraph is excellent. Also, while in the “old days” we could afford to wait until a feature is stable before documenting it, that’s not true any more. Agile teams frequently develop a number of features in parallel and they all become finalised just before release date. So as a technical writer, we have to follow the agile process and document the features iteratively too. Otherwise we just can’t keep up.
    Cheers, Sarah

    • Susan points out a big impact of agile development on documentation is that technical writers must follow the agile process and document features iteratively. This is where the idea of simplicity makes most sense because technical writers should only document features that are stable, rather than speculate on what the product or service “should do” (as may be the case when the documentation is based on the engineering specification rather than working software).

  3. Pingback: On The Fly (Part 2) « Outside Looking In

  4. Tone of Joe’s reply sounds like he agrees w/ Sarah but text sounds like he disagrees: Sarah saying we can’t affort to wait for a feature to become stable b4 writing about it. Joe saying “technical writers should only document features that are stable”. Am I misreading what’s being said?

    • I apologize if the article left some confusion on this matter. My reference to Scott Ambler’s article does state that features should be stable before they are documented, but I do acknowledge that this is more an ideal than a rule (as illustrated with my experience with documenting tasks while the administration console was still being changed). Sarah and I agree that communication with the project team is key to determining when a feature is stable enough in a given software build to be documented.

  5. This is only a sketch but I think ties into your thinking very well. BTW I see no mention of ‘story’ which is the kernel of where doc heads off into working software in Agile… it is at that juncture where I would see TWs becoming UX designers. http://www.sleepingdeer.com/yawp/?p=141

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 )

Google photo

You are commenting using your Google 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 )

Connecting to %s