Agile Source

If you are working in an Agile environment, and don’t have “single source” in mind when you write then you are slowing yourself down.

Working in an Extreme Programming environment (an Agile methodology that our Development Group follows) brings a unique set of challenges. During the early stages of a release, we spend a couple of days thinking about what we will be building, writing out the requirements as customer-focussed stories and breaking down those stories into discrete, small, chunks of work each of which has an estimated time for completion.

We don’t have a project plan, and as we work in tight iterations with functionality being released on a regular basis, there is always the chance that the scope will change at some point, generally with little warning. The system is built to deal with this so it’s not as bad as it sounds but it does throw up some challenges for the technical writer.

However with a little thought and awareness it’s a very easy system to work within, but does mean we need to push into other areas a little more.

First up you need to get involved when the developers are writing up the stories. Sit in the customer meetings and any planning meetings. Be the user advocate. Ask questions now. Stories are written from the perspective of the customer (with that customer being the person who requested the functionality) and you can (should!) help to craft these properly, making sure each story remains customer and real-world focussed. Every story, regardless of the functionality that will eventually support it, is a high-level requirement and should be stated as such. The actual work might be to make an object persistent, but the story will only say “The customer wants to be able to view previous transactions for each account”.

You should also be present during the break down of the work. At this point, with each story being broken down into small chunks of work for the development team, you can gain a better understanding of the functionality, including any presumptions and dependencies that may be added. Each piece of work should be no longer than a few days, less is better, and you can start to build an idea of the scope of work during these discussions. As yet I’ve not found any direct corrolation between X days of development work to Y days of documentation work.

So, from the stories, you should have a good idea of the high-level functionality that is being produced, and you can create an outline of the documentation that is required. You should also, having sat in on the discussions, understand the requirements of the customer and the reasoning as to why a certain piece of functionality is, or isn’t, being developed.

The chunks of work can help to feed into each section in your outline, and working to the same principles as the development group, you can estimate each section. Even if the figures are never published, it’s a good idea to take a stab at guess-timating the work based on what you know, allowing scope for research and playing with the software. These guess-timates also re-enforce the fact that you will be working on discrete chunks of work at a time, which should help you cope for descoping of functionality by the development team.

The speed of change is what makes Agile development so popular. If Agile development is the speedboat, the more traditional development approaches are most definitely the oil tanker. Slow to get moving, and hard to stop if a change of direction is needed. Understanding how the work breaks down, and writing in a style that helps encourage and support that, you should be writing discrete chunks of information that can be used anywhere.

In other words, you should be writing as if you are in a single source environment, even you don’t have a database or CMS in place, even if all that content is being held in one document. The principles and structure that single source systems promote will allow you to keep pace with development.

Be the speedboat!