Musings on documentation

One of the challenges of institutionalisation for a system such as talks.cam is documentation. As projects pass from hand to hand through a process from innovative idea, through some kind of incubation, through to a fully supported service, people develop software, publicise their work, encourage others to use it, and answer questions, but very rarely do they update the documentation.

Static documents which describe what you might use a service for, and how to do it, are not fun for most people to write; it's hard work to put together coherent and useful documentation, and requires a great deal of organisation, communications skills, and empathy with the range of users (and visitors!) who might drop by your site and wish to learn more. Some readers will have problems they are trying to solve; others are simply trying to understand how something works. Some will wish to read up on a service thoroughly before they dive in as users; some will be "power users" already who are struggling with one particular tricky and perhaps obscure task. Catering to all of these with one main "help" page and contextual links is hard work, and it's perhaps understandable why software developers avoid it.

We've been tracking our helpdesk queries for Talks.cam since CARET took over the service, and also gathering comments from visitors and those who have come across Talks.cam from different places. It seems there are some frequently asked questions, which aren't being addressed by the current documentation, and so we are now undertaking a update of Talks.cam documentation, which should help new users get started, visitors see what it's all about, and existing users be empowered to get the best out of all the wonderful features built in to talks.cam.