Tag: <span>User Guide</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…


Ever get the feeling that no-one reads your documentation? It’s a frequent issue amongst Technical Writers and the general stance reflects the approach many take to make sure that, when someone finally picks up the documentation, they can get to the information they need as quickly as possible.

Given that, there is little worse than to have errors reported in your documentation. After all, if they’ve only just started using it to help them solve a problem and one of the first things they spot is an error then it’s understandable that confidence drops and that they are less likely to go to the documentation in the future.

Of course we all do the very best job we can, yet the fact remains that mistakes happen, errors occur. The reason that this tends to be a bigger issue for information is down to how we process the knowledge we have.

Without getting into too much detail, learning is a continuous process and most of that happens when you are doing things, using the tools at your disposal and figuring out how they work and how they help you achieve what you are trying to complete. By the time you decide to check the documentation, you’ve (usually) got a good bank of knowledge already, and it’s building all the time.

So, when the documentation is wrong (regardless of whether the reader spots the mistake immediately or only realises it after trying out the instructions) it seems to be an obvious mistake. After all, if I can figure out how to do X, why is the documentation wrong for Y, it’s just the same process?

Software applications that have minor errors in them are tolerated because they are the tool and sometimes there isn’t an alternative. You learn how to accomodate those errors in the application and work around them. You can’t do that with documentation, it’s either right or wrong (ambiguous documentation is presumed wrong) so confidence in the rest of the information is linked to those initial few instances of usage.

We all have review procedures that should capture errors in the documentation, we do our best to think about how the user will be interacting with the product and base the structure and content of our documentation on that information, and we all receive that email that says “On page XY of the User Guide, it states that…” and our hearts drop a little.

However I think we should embrace those moments, be positive about them! You have a user who cares enough about the documentation to complain and I think it’s worthwhile thanking them for pointing out the error, tell them that it will get fixed, and encourage them to continue to let you know if they spot anything else.

So next time you get one of those emails, or a bug in the documentation is raised, be sure to follow up with the user and thank them. They are proving that people do RTFM.


Comments closed

We have two digital handsets at home.

They are made (as says the sticker on the box) by Ascom.

Ascom’s website is here: www.ascom.com.

Their support website for handsets (terminals), taken from the handset User Guide, is here: www.ascom.com/terminals.


Comments closed