Thursday, August 2, 2012

Writing documentation in an Agile environment

Agile was created by and for developers, and documentation does not fit naturally into its processes. Doc managers need to be proactive about integrating writing into the process. In my experience, doc departments take too passive a role.

Here are some of the difficulties with putting tech writers on Agile teams:
  • For much of the Agile process, the software is not finished enough for writers to begin working on it. If writers start writing before a feature is complete, they may have to do a lot of rewrites. This can be a time waster. It can also lead to mistakes in the end process, especially if aspects of the feature are mentioned in several deliverables.
  • Depending on the writing requirements of each Agile project, a writer might need to be part of multiple projects. I was once on seven active Agile projects at the same time. It's not feasible for a person to attend seven daily standup meetings, even if they're only 15 minutes each.
  • Agile is designed to get developers to act as teams, so it includes every Agile project member in scoping and other team decisions. It is not necessarily useful for writers to participate in those decisions.



When figuring out how to fit into Agile, doc teams should keep the goals of Agile in mind. See your company's Agile evangelist for details for your company, but my initial list of goals would be to empower employees, create super-functional teams, reduce useless bureaucracy, create user-focused output, and respond quickly to market needs. Doc managers should go to the team that organizes Agile in their company and provide that team with some rough requirements for integrating writers into Agile. After that, it's a matter of working with the Agile team to finalize a list of goals, requirements and rules for writers. (There might be different sets for different levels of writer.) Every context has its own needs, but here are some sample doc goals, requirements and implementation rules. (Note that this is not intended to be a complete or cohesive set; plus, ideally the goals, requirements and rules should align.) Sample goals:
  • Writers should have more and better communication with developers.
  • Writers should have a thorough understanding of users, the market and the product.
Sample requirements:
  • If there are no product specs, the writer needs comprehensive use case scenarios, a working sample to test, etc.
  • The doc manager will not be on the Agile teams, but needs to evaluate and prioritize resources.
  • Writers should sit with the developers on their Agile project.
  • Writers should review terminology and usability issues early in the design phase.
  • During the project, writers should review resource strings (error messages, UI text, etc).
  • Writers {need to | should not} participate in multiple Agile projects at the same time.
Sample Agile implementation:
  • If a senior writer is on an Agile team, the writer should assist the Product Owner with the creation of user stories.
  • Writers should attend only review meetings until they start writing.
  • Writers should start writing when the feature is complete, stable, and has been tested.
  • Writers should write throughout the process, documenting every iteration.
  • Writers should work one iteration behind the rest of the Agile team.
  • The writer should be considered a Stakeholder for the project.


Re the requirement that writers will begin documentation only when a feature is complete and tested, Development may want iterations of the product to be documented for internal testing or other reasons, which is fine - but may require more writers. In addition, if a company wants to continuously deliver software updates with docs - and do it at a lightning fast pace - they might have to realize that doc productivity will fall and they'll need more writers.

I think the reason that doc teams aren't proactive enough in stating their requirements is the way that Agile is often introduced. There is a lot of emphasis on denouncing other processes, assimilating employees, and broaching no dissension. (This is a lot like the way DITA typically gets introduced.)

Agile evangelists (like DITA evangelists) frequently feel that the most important issue is employee attitude, and they are overly sensitive to anything that might be considered negative. But docs simply aren't an easy fit for Agile, and it's important to figure out where the problems are before devising a solution. All too often, writers are just made members of Agile teams and left to muddle through - which usually doesn't work very well.

2 comments:

  1. Ruth, I have to disagree with you on this. While a traditional docs process is not a good fit with agile, an agile docs process is a great fit with an agile development process. Getting there does require a bit of a broader perspective though. Agile is, in many respects, an application of Lean Thinking to software development. What you want in docs is not so much agile applied to documentation as a documentation process based on Lean principles.

    And while Lean does emphasize the elimination of waste, I think it is a mistake to say that the writers should not begin documentation until the feature is complete and tested. Not only is this often impractical from a commercial point of view, and potentially disruptive of development's requirements for frequent deliveries to the customer, it also isolates the writer from the learning that is supposed to be the core of each story development. Ultimately, it is learning time, not writing time, that determines both docs quality and docs cost. Agile is a method based on optimizing the development process for maximum learning, and the writer should be part of that, both for their own sake, and for the sake of the wider team.

    ReplyDelete
  2. Hi Mark,

    I'm not sure we disagree. I'm not necessarily in favor of the writer waiting to the end of the project to get involved in the team, I'm just saying it's an important consideration that needs to be thought out with the people who set up Agile in the organization. In the case of a writer being on 7 Agile projects at once, it's not possible to participate in all Agile meetings. In other cases, the company might need to hire more writers.

    I favor a setup where writers are embedded with developers and attend developer team meetings, participate in developer decisions, review terminology and resource files, conduct usability tests of the software and documentation, and so on. It's a matter of seeing how to make that work in an Agile environment.

    I do disagree with what I think you're saying about an Agile docs process. The docs should be designed based on what the readers want and need, not based on the development model that is used by R&D. That's where I think Doc managers are being too passive. We always have to make compromises, but we need to work out what's needed and then work within the organization to do the best we can to deliver it.

    ReplyDelete