Agile end-user documentation tooling

Bas Geertsema

One of the most overlooked aspects in any software project is the end-user (e.u.) documentation. Can you recall how many (web)applications you have encountered that had proper e.u. documentation in it? I for one cannot, even though the (web)applications are getting more sophisticated and more complex every day. And to be honest, the software projects I create often lack proper documentation as well. So why is this the case? There are a number of reasons that I can think of:

  • Typically developers don’t like writing end-user documentation. It is just way cooler to create new functionality than write about functionality you have already written.
  • Developers are not the right people to do it anyway, you need a customer-perspective. That is where the role of a technical writer comes in.
  • E.u. documentation is often written when a product is already finished. When the development of a software product is already over-time and over-budget it is extra hard to convince the customer or projectmanager to put even more time and money in it to create proper documentation.
  • The available tooling is not sufficient or well-known enough

Just some pitfalls here. But most people do agree that end-user documentation is important. For the acceptance of any new system it is a vital part.

How can we adress these problems? On my quest for the right tooling I have not found many good products. There are soms tools that let you generate documentation help files, or even create tutorial videos. But they are by their nature very loosely coupled with the actual software product and development process.

As part of my education I have enrolled into a course where I will be able to explore this problem more in depth, and provide a solution for it. My idea is to create a usable tool that can be pragmatic used in an (agile) development process and establish the link between the developer and technical writer. Furthermore, I want to be able to make e.u. documentation part of the build process and also be able to break a build if the documentation is not correct. In the coming weeks I will think hard about how to create this philosophy into a concrete product. I will keep you updated!

comments powered by Disqus