Tag: <span>Agile</span>

Recently Daniel Brolund posted an idea around something he termed User Guide Driven Development, it’s an interesting read and, you know what, he’s almost right.


First up you should note that Daniel works for the company that created the application he name drops in his post, Bumblebee. However his approach did ring a few bells with me, as it would sit nicely alongside my belief that, when working in an agile development environment, you have to eschew traditional writing processes and aim to grab and pillage information from wherever you can, trickling into what will become the final publication.

What I’ve realised is that by partly adopting the process suggested by Daniel we, the technical writing team, can be involved right up front and the documentation can be one of the methods used to validate the software as it is being built.

In an Agile team, the emphasis is on Test Driven Development where a chunk of work, derived from a customer story, first has acceptance tests written for it before any coding can start. The aim of the developer is to make sure his code meets the acceptance tests. In our organisation the test team provide guidance and input to what those tests should be, but the onus is on the developer to make sure they write the tests first.

So what if we slip the technical writer into the mix? Well first up we can roll up a level to the requirements gathering point and rather than one or two developers talking to the customer to capture their requirements in the form of customer stories (with the customer being the ‘sponsor’ of the requirement and not always directly a customer of the functionality, for example in the case of a sales or marketing driven stream of work) instead the technical writer will be there to capture the stories and flesh them out to an appropriate level.

From there it should be easier to break the stories down into tasks, and as we act as user advocates, those tasks should better reflect the end user. Once the tasks are in place we can write up the documentation to that level alongside the creation of the acceptance tests and, with both tests and a few paragraphs describing the aim of the functionality (how it helps meet part of the overarching customer story), and how the functionality is expected to work (how the end user will use the functionality), then we have a very powerful way of ensuring requirements are met.

As it happens on the guys in my team is already working in this sort of manner and it’s going well. Yes it’s a mind shift for both the technical writer and the development team but it appears to be paying dividends. If everyone agrees we’ll roll it out across the other areas of development.

And then, finally, I will be able to claim that my department is running development! Mwuhahahaaa!!

OK, maybe not.

P.S. I’m aware some of my colleagues read this, don’t worry I know who you are, and you will be treated fairly when my team assume power…


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.


“There is no such thing as too much information”

We’ve all heard this statement at one time or another, and in the internet age it’s accepted as a statement of truth. Which is shame as it’s completely wrong. Turns out, that you only need enough information, not all of it.

A while ago I wrote up some thoughts on how to integrate an authoring team into an Extreme Programming (Agile) development group. The post Trickle vs Traditional outlined a basic way of building up the required content throughout the various stages of an XP release and, to save you re-reading that post, let me grab the crux of what I was saying:

The trickle method relies on the ability of the technical author to retain a “big picture” view whilst working on multiple chunks of information at any one time. The information will not come in a set order, nor from a definitive source, instead it will trickle in from various parts of the development team, testing, and so on. Your job is to monitor the flows of information, position yourself within a stream (or two) and divert the information you need into the documentation.

In reality this means that you need to develop a good technique for filtering information, knowing when and what to leave out of the documentation and relying on your knowledge of the product to help you make decisions and make them quickly.

Quite simply, to remain agile in such a system you need to be able to make decisions. A decision can be wrong, as long as you make the decision to fix it as soon as possible.

In a way, you start to write by instinct, trusting that you properly understand all the myriad of factors that influence what information you are creating and letting your talents as a technical writer take over. As Malcolm Gladwell, who wrote an entire book about this type of decision making, suggests:

We live in a society dedicated to the idea that we’re always better off gathering as much information and spending as much time as possible in deliberation. As children, this lesson is drummed into us again and again: haste makes waste, look before you leap, stop and think. But I don’t think this is true. There are lots of situations–particularly at times of high pressure and stress–when haste does not make waste, when our snap judgments and first impressions offer a much better means of making sense of the world. [source]

All of that sounds slightly scary if you are currently working in a process-heavy environment, with requirements and specification documents been seen as a way to provide all the information everyone needs, and which are typically a rather slow cumbersome way of handling information.

Anyone who has written such a document knows how hard they are to do as you can’t know everything at the start of a project and over time things change. Having previously worked in ISO regulated companies, where the audit history of a document was almost more important than the information in the document itself, I know how onerous, time-consuming and false those systems can end up being. Many is the time when everyone in a discussion knows what is going on but you still have to write it up, review and approve it, before it can be officially logged in a system that is rarely referenced.

Monitoring the flow of information, trickling it into your documentation as and when needed, making quick decisions and trusting your instincts certainly feels like a more natural way to work. It does mean that there is no such thing as a final document and there is a chance you will publish something that is wrong; yet it is the very possibility of that happening which keeps itself in check. Allowing people to make their own decisions instills a higher level of professionalism and lowers the number of errors.

It’s not suitable for everyone and some industries wouldn’t enter it but it’s an interesting way to work. Limiting the amount of information you have available, and making decisions based on those seems wrong but it does work. You just need to be brave.


Comments closed

The following is taken from current experience, fitting a Publications team into an agile (XP) development methodology. It’s very much a work in progress…


In a more traditional development environment, there is likely to be specifications and design documents on which you can rely. This is not the case in an agile development environment, with requirements focussed around user acceptance, and a heavy reliance on word of mouth (through pair programming) and shared knowledge. It may sound chaotic, it is not. Each piece of functionality is assessed and if there is not a direct requirement for a piece of functionality it doesn’t get done, similarly each piece of functionality is stated as a story, and will have an index card created which can be used to track the story through various stages.

To match the pace of software development, the Publications team needs to adopt a similar approach. Rather than waiting on information to come to us, we need to be involved, engaged and pro-active in learning and understanding what we are documenting, and breaking out of the old authoring model.

Previously large chunks of documentation were written by the same person, often at one sitting. You’d outline a chapter and start bashing in the words, investing a lot of time and effort into your ‘baby’. That concept is no longer applicable.

The trickle method relies on the ability of the technical author to retain a “big picture” view whilst working on multiple chunks of information at any one time. The information will not come in a set order, nor from a definitive source, instead it will trickle in from various parts of the development team, testing, and so on. Your job is to monitor the flows of information, position yourself within a stream (or two) and divert the information you need into the documentation.

As such, the technical authors will be sat within development teams and are expected to attend all designing and planning meetings. Understanding as much of the work as possible, as early as possible, will benefit the documentation, and having a technical author in place at the beginning of the development process will benefit the product. Be the user advocate, keep the tasks they will be performing in mind and strive to contribute as and when you can.

This way of working is different, and does mean you need to adjust your mindset somewhat.

You will not:

  • Be able to write entire sections in one go.
  • “Own” the document you are working on.
  • Always finish what you started (but only if it’s planned that way!!).

Hopefully this new approach will make us much more involved in the day-to-day development of the product, and by bringing additional benefits to the development team, will increase our standing with them.