December 18, 2009

Agile Tenet #2 – Welcome Changing Requirements

Filed under: Uncategorized — heratech @ 11:12 am
Tags: ,

Two fingers, V for victory Second 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.


Welcome changing requirements, even late in development. Agile processes harness change for the customer’s competitive advantage.

Early in my TW career a product manager changed a toolbar icon a week before a release. I updated the User’s Guide to reflect the new icon. A day before the release he changed his mind, and reverted back to the original icon, but didn’t tell the doc group. Luckily it was a beta release, so the incorrect docs only impacted a single customer.

While technical writers may not actually welcome change, most of us have had to adapt to the reality that developers often make changes the software and forget to tell us. Getting TWs to welcome change? Well, that may require a major attitude adjustment for some of us, as whingeing about how we get no respect is as much a part our perception of our jobs as it was part of Rodney Dangerfield’s comic persona. Many of us spend our days trying to earn that respect by subtly reminding our coworkers that we provide customer value too.

I think that part of the value of a technical writer is often found in the types of questions that they ask about the products that they document. When I was first investigating technical writing as a career change I attended an information session for a TW certificate course. The speaker was a graduate of the program whose previous career had been as a journalist. I remember that he said that his new career was much like his old career; he still spent his days interviewing people, then going back to his desk and writing. Ever since then I’ve looked at my work as a form of investigative reporting.

For example, if the new feature is to allow the user to create or change a password, I might ask the following questions:

  • Can the password match the user name?
  • Are there any length requirements or restrictions for the password?
  • Is the password case-sensitive?
  • Are there any requirements for the first character in the password?
  • What special characters are allowed in the password?
  • Does the password expire?
  • Can you reuse passwords or partial passwords?

When would it be more helpful to the project to have the technical writer ask these questions? Would you rather have them ask the developer after the code is complete, or ask the customer or product owner during the Sprint planning process, while you’re writing the acceptance criteria for the User Stories?

Agile processes harness change for the customer’s competitive advantage.

So not only do TWs need to welcome change, we need to figure out how to harness it for our customers. I think one of the ways that we can do this is to keep up with the changes in technology and how information is shared in the Internet age. There are many new options for delivering content to our users. Yesterday my former manager sent me a link to the documentation Wiki that he’s working on. And there has been a brief discussion on the TECHWR-L mailing list recently about using WordPress as a documentation platform. I’m still waiting for my copy of Anne Gentle’s Conversation and Community: The Social Web for Documentation to arrive. I’m looking forward to finding more good tips for harnessing Web 2.0 for my customers in her book.

This tenet ties into one of the core TW goals, to understand users and their tasks so that we can write useful documentation. I think the trick for the Agile team is finding the right balance between understanding the user’s requirements and reducing project documentation so that you can get down to the business of creating the product. Technical writers, with our user focus, can help our teams remember that the goal is to meet our users’ needs, not just deliver working software.

Create a free website or blog at WordPress.com.