For the past couple of years (since May 2009) we've used Flossmanuals to write our CiviCRM books. In August this year, our old faithful Comprehensive guide to CiviCRM became two: The CiviCRM user and administrator guide and The CiviCRM developer guide. The user and administrator guide is now in its fourth version and we're currently writing new training guides for administrators and developers. We are also experimenting with sector specific introductions and it feels like we are headed towards a pretty comprehensive set of documentation for CiviCRM.
Up until now, the books have lived in their own little orange world on Flossmanuals, and while that orange world (filled with strange creatures like Booki and Objavi) has been good to us, we've wanted to move our documentation closer to civicrm.org for a while. There are lots of good reasons for this, including better control over the link structure, versioning, and making them look more like CiviCRM products.
I took the oportunity at the European Code Sprint to get them over here. Following Adam's advice, I wrote a publishing script based on bookipublisher, called BookiPublisherLite, that asks Objavi to get a book from Booki, downloads it from Objavi onto CiviCRM.org, does a bit of tidying up, restructuring and formatting, and then publishes it at book.civicrm.org. (Are you with me so far?!)
At the moment we have:
You can also see archives for each book by clicking on the archives link in the footer on each page, for example http://book.civicrm.org/user/archive. The lack of archives and versioning has caused us problems in the past, and meant that links from the forum stopped working when we published new versions of the book. Now when we get a 404, we can display a helpful page which suggests pages in older versions of the book along with a warning that they may be viewing out of date content.
Our plans now are to hold two book sprints a year, which we think will be enough to keep pace with changes in CiviCRM. We'll likely alternate between one in the US and one somewhere else.
Right now, we are carrying out a review of the user and administrator guide. I know you were planning on curling up with a good book this holiday season, so why not make it The CiviCRM user and administrator guide? You're welcome to read a section or more of that and let us know what is missing and how it can be improved. See the review guidelines on the wiki for more details.
If the above sounds like exciting stuff to you, it would be great to have your involvement in the future of CiviCRM books. Let us know your thoughts and how you can contribute below.
Comments
Well done.
... on CiviCRM.org. We've updated links in various spots and added a primary navigation link - Getting Started - which points to the books. Great job!!!
Congratulations to all involved, and especially yourself Michael. It's much better to have the documentation in-house, as it were.
A couple of queries about where this now puts us:
The flossmanuals documentation will become the "working copy" that folks can contribute to. How will changes to the flossmanuals documentation be reflected at http://book.civicrm.org ? Will this be a 'live' synch or a periodic update?
And how does the wiki fit in to this workflow? Is information being drawn from the wiki into the flossmanual and thence to http://book.civicrm.org?
Thanks
Graham
As I remember our conversation at the NYC Sprint, we will move the working copy to book.civicrm.org in sync with new releases of CiviCRM.
The wiki will transition to information that changes often - installation and upgrade comes to mind - and for documentation of new features. New feature documentation will then be integrated into the book. We plan to add a documentation phase to the development workflow, assuming we can recruit enough documentors!