No 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.

Written By

Long time blogger, Father of Jack, geek of many things, random photographer and writer of nonsense.

Doing my best to find a balance.

More From Author

You May Also Like

Reasons to work

Hotel Life

Everything changes


Kat says:

Some people believe that XP is the Emperor’s New Clothes of software development, and one of its shortcomings is that it by definition undermines the role of documentation.

Management like it coz it’s cheap and they don’t want to spend money on a QS, and developers don’t like writing. Matt Stephen’s discusses docs in his XP critique:

“XP makes a big issue about its core value of Communication. This is wonderful, as communication is definitely a key factor to the success of any project, XP or otherwise.

Unfortunately, XP also makes a big issue about not doing any documentation (or at least very little, or none at all). I think this is partly why XP has such a broad appeal amongst earnest young programmers. After all, documentation really sucks, right? Just like homework always sucked.”

You can read his full review at:

Where I am at present, the technical writers are well integrated into the development teams and we manage to produce some pretty good documentation by staggering (trickling as I call it) the information in throughout the dev cycle.

I think XP has a place, but I think there needs to be some additional thought on the information debt being built-up by software companies that don’t agree with the title of this post.

Thankfully I’m not working at such place, nor have I!

Completely agree that no docs = no product. In fact, technical writers are the caretakers of life, the universe, and everything πŸ˜‰

I’m lucky enough to be working for a company which totally gets documentation. But I have had less fortunate experiences in the past.

And currently, I’m in a very *agile* environment. It’s a lot of fun, and very rewarding. We’re a team of tech writers, and we’re continually on the move and adapting the way we work as well as the docs themselves, to suit the agile environment.

Synchronicity rocks. Often the tech writers and the engineers find themselves working on the same aspect of the product, even when that’s *not* planned.

Seeya on the page πŸ™‚

Comments are closed.