Recap of the Apeldoorn and Butcombe documentation sprints

We've tackled a fair amount of work at the recent Apeldoorn and Butcombe documentation sprints.  As well as documenting pretty much all of the new features for 4.2 (including SMS) - special thanks to Simon West for doing so much of that - we've made some significant improvements to our infrastructure, reviewed a few sections in the book, and added a number of areas of work to the documentation road map.  It feels like we are getting into a good rhythm these days with a book sprint every 6 months enabling us to keep fairly up to date with the release cycle. Never the less, the list of things to do keeps on expanding, and there is certainly lots more that we (and the we includes you!) need to do do to improve our documentation.

Every book sprint is unique and different to the last but we are realising that there are quite a few things it makes sense to do at each one.  We've made a wiki page that bullets those tasks and gives other hints for running a documentation sprint.  If you are interested in holding a documentation sprint, you should find it a good starting point - and you should definitley let us know if you are planning a sprint and we'll be happy to support you.

Some of the infrastructure improvements should make a big difference to how accessible our content is.  You'll be pleased to hear that we now have the ability to search both the user and administrator guide and the developer guide.  Searching is done courtesy of google (excuse the ads for the moment - we'll hopefully remove those soon) and we hope will considerably improve the ability for people to find what they are looking for.  We've also added downloadable PDF and epub versions of each book (and I am keen to hear feedback from people on how these work on your screen readers, etc.).  And you also now have easier access to older versions of the book, e.g. book.civicrm.org/user/version/4.1.

We've come to the conclusion that we are being let down a bit by the poor structure of the sections of our book and have started a project to tackle this.  We tried restructuring the entire book at a sprint before, and it turned out to be quite a mamoth task so we are thinking that from now on, we'll aim to do a couple of sections at each future sprint.

We are also looking at new ways to manage our workload and have talked about using our issue tracker to allow people to submit documentation issues. We think the issue tracker could really help organise the work load, helping us to sync documentation work with releases of the software, and helping us co-ordinate work outside of the sprints.  Closely linking the documentation work processes to our code base should enable us to do cool things like have developers open tickets for documentation that needs to be written, and get documenters in the habit of opening issues for usability improvements that they discover while documenting.

Some things to add to our wish list...

• There is still not a clear and simple path for people that want to contribute to the books.  Adding a bold 'get involved' link below the pdf and epub versions of the book would be useful (if someone wants to add that, edit this file).  Also, adding comments to the book in some form would be very useful: http://disqus.com/ or http://disqus.com/ might solve that problem. Let me know if you want to implement that.  Unlike the wiki, we are keen to retain release cycle for the book (with trunk, and stable versions, and a release process for quality assurance).
• A couple of things that would really improve our editing environment (currently booki) would be the ability to fork and merge versions of the book (e.g. so that Joe Murray can work on CiviAccounts documentation over a couple of releases but we can still release in the mean time, and then merge when appropriate).  And also better wysiwyg handling so that we can do code blocks, etc., which is especially useful for the developer guide.

Thanks to all the documentation sprinters over the past two weeks, you can see the latest versions of the books online now at book.civicrm.org.