Last week I spent most of my time facilitate our retrospectives, that is I spent a lot of time chairing meetings, encouraging and monitoring debate, and far too much time manipulating Post-It notes. Let me explain.

Within the development group, we base our working practices on Agile development and part of that suggests that at the end of each release cycle you should hold a retrospective session to pinpoint things that went well, things that didn’t go so well and to assign actions which will help improve things next time. It’s all about continuous improvement and we do get a lot of benefit from them.

Don’t be put off by the name, it’s essentially a debrief session that is focused on a particular area, and the process is quite simple although ours has changed a few times and the sessions we held last week were, again, something new to try and improve the retrospective process (we actually hold retrospectives of the retrospective to make sure that the retrospective is improving as well… ).

Our development group is broken into teams, and each team is asked to consider their own working processes within the overall adoption of the Extreme Programming methodology (the branch of Agile development we follow).

And then it’s Post-It note time!

Each team member is given a pad of Post-Its, and we spend 10-15 minutes jotting down things that went well, one item per Post-It. Once the time is up they Post-Its are stuck up on a wall or whiteboard, and grouped into common themes. Then we do the same for the things that didn’t go so well (ok ok, “what went wrong”) and again they are stuck on a wall and grouped.

The common groupings in each category give you things to continue doing (what went well) and things that need improved (what went not so well). Then comes the fun bit!

Each team is given control of their own working processes, and are encouraged to discuss and decide on actions to improve the process where it’s been identified as being weak.

We then gather each team together for a reporting session at the end of the week, during which I teased out the common threads in each category, the items that everyone identified. That final session was interesting, and suggests that, despite having been split into small teams (8 people per team, including 1 tester and 1 technical writer) everyone identified some similar issues, and everyone agreed that certain things were working well.

One of the common “what went well” topics was agreement that having a tester and a technical writer embedded in the development team was of benefit, something I thought but hadn’t ever received feedback on until now. That was a nice moment.

Call it a debrief, call it a retrospective, but an honest appraisal is hugely beneficial. It can be hard, and at times the discussions were heated, but everyone was honest and upfront and we should see the benefits over the coming weeks of this release.

Now, does anyone know what I can do with a few thousand Post-Its??

UK readers, Skill Matters are running a session on Agile Retrospectives next week.

bookmark_borderAgile 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!

bookmark_borderNo Docs = No Product

What of agile documentation?

It seems like such an old argument that surely, SURELY, doesn’t need revisiting? Alas it seems that the world of software engineering still contains those who think that code = product. Thankfully, in my experience, the numbers are thinning as most practitioners of modern software practices are at least educationally aware of the need for product documentation, even if they don’t fully understand the reasons. However, there are still those who are happy to hack away, and then claim they have a product. If you are such a person let me make one thing clear, you are wrong.

Not only are you wrong but as time marches on, you get further and further from being correct, all the while creating further problems for you and your product.

Just over a year ago, in preparation for my new job, I spent sometime reading up on Agile development and in particular I focussed on Extreme Programming (XP). The more I read the more I came to realise that this was an area which was popular with developers, yet had little to no mention of product documentation as a fundamental part of the methodology.

Mention of unit and acceptance testing as fundamental parts of working in XP suggested there was at least an understanding of the importance of solid, well constructed tests to help make to a “better” application (test-driven development) but the more I read, the more I become slightly disconcerted at the lack of consideration given both to the production of product (end user) documentation or of the benefits and skills a technical writer can bring to a development team.

Truth be told, I’ve still to find more than a passing reference in any of the more recent publications and articles I’ve found but I’m happy to be proven wrong. Perhaps I’ve been reading the wrong things, and visiting the wrong websites? Or, more worryingly, perhaps there really isn’t anything out there.

Obviously, as a technical writer, the role of product documentation as part of the product is something that is at the forefront of my mind, and I’m not expecting any software engineer to have to worry about such things beyond understanding that we are a fundamental part of the product offering and hopefully agreeing that there is a level of expectation setting to be undertaken.

That said, I do expect a software engineer to understand that software without any support, be it formal documentation, training, or a dedicated support team, is NOT a product. If we can’t agree that fundamental trait then perhaps that problem requires a solution (thankfully, as I said earlier, I don’t think it’s a huge issue at present).

Quite simply, products include documentation, support and training, and tell a cohesive story to a potential buyer. A story that says, yes this product will do X, Y and Z, and if it breaks we’ll do our best to help fix it, and we’ll support you as you learn to use it throughout the lifetime of your relationship with the product (and, therefore, the company).

Admittedly the lines are blurring, with better UI design there is less need for the end user to head to the documentation for assistance but I’d argue that, conversely, as UI design improves and more people become aware of the basic principles of software applications (we all know cut and paste by now, right?) then the end users will start to stretch the applications in ways that hadn’t been considered and it is at this point that product documentation (information) becomes the key differentiator between products.

Of course it is possible to happily exist as a technical writer in an Agile world, but I think we need our voice to be louder.

So I guess my question is, who is willing to shout?

Note: I am aware of Agile Documentation, but I’ve yet to read it. It seems to be more focussed on a developer writing documentation though? I’ll post a review of the book soon.

bookmark_borderDilbert does it again

I really don’t know how Scott Adams manages to tap into these things, or is the software industry REALLY that similar the world over?

Regardless suffice to say that, in our Extreme Programming (XP) development group (XP is a form of Agile development), todays’ Dilbert raised a bit of a chuckle:

(click for bigger)