User documentation in an agile environment

I’m currently working on a draft for a proposed new standard on developing user documentation in an agile environment. There is a lot of information out there about agile software development, but most of it is focused towards code developers, and possibly project managers. What I have noticed is there is very little advice out there for information developers, technical authors, and information architects like myself. I have also spent the last 18 months or so going through the somewhat painful experience of changing from a waterfall style development methodology to a more agile approach.

One of the things that really worried me about agile development when I was first introduced to it, in a two day education course, was the statement that ‘we prefer working software over comprehensive documentation’ from the agile manifesto. Now I know that what they mean is they prefer to make the software work rather than write detailed specifications about how it will work. The trouble is ‘user-documentation’ is often seen as secondary to the software product, and I was nervous that documentation in this case would be read as including user-documentation. I think it is a valid concern, and the lack of the role ‘technical writer’ or ‘information developer’ out there in the world of agile articles also worries me.

After some initial scepticism, I can see the value of it. And I also have a much better idea of how it can work, and also how it can fail to work. Because the emphasis in agile is on reducing life cycle documentation, then there is a risk that if the user-documentation development team are not a part of the agile process, either because they are not included, or because they are trying to hang on to the ‘old way’ of doing things, then they are going to lose out. Partly because they will struggle much harder to know what they should be writing, and partly because they will miss out on a new opportunity to actually work much closely with their team and gain the chance to either learn from or represent the users, and actually influence their product for the better.

Working software over comprehensive documentation

One thought on “User documentation in an agile environment

  1. Just to throw my two cents in…

    My first agile experience was a positive one and part of this success was based on having a technical writer available to us for half the day (every morning including our standup). They handled all user and install documentation.

    All other documentation was reversed engineered from our tests and a few abstract diagrams to tie it all together. Our UX maintained wireframes and siteflows, but this was to facilitate conversation within the team more than aid the end user.

    When it comes to documentation, less is typically more in large companies going agile. I think Alistair Cockburn’s approach of focusing on the end game is the best way to understand the right amount of documentation.

Leave a Reply

Please log in using one of these methods to post your comment: Logo

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