A quick look the book CiviCRM a comprehensive guide: how we got here, and our plans for the future
We recently got fifty copies of CiviCRM: a comprehensive guide printed on demand for some training events in the UK. Being able to hand out a 300 page book as a supplement to the training went down really well with participants: holding something in your hands in a world which is predominantly online world is quite reassuring, it seems!
Getting hold of hard copies of the book at short notice was quick and painless. Objavi (Flossmanuals new and impressive publishing engine) just worked, creating a great looking PDF that we sent to Imprint, a local printer. Imprint were a recommendation from the Flossmanuals list and I would definitely recommend them to others that need books printed in the UK - they turned the PDF into 50 books in less than 24 hours at the price of £6 ($10) per book and were helpful, fast and professional.
Integrating the book with training was cool, and it made me want to write a little about how we got here, and our plans for the future, so ...
How we got here
The current 'second edition' of the book is the result of two book sprints and some sporadic contributions between. As the title suggests, it covers pretty much all of CiviCRM’s functionality. It also includes introductory sections to help non-profits decide if CiviCRM is right for them, to assist them with project management, and introduce them to the CiviCRM community. At the back of the book is a 'developer' section for people that want to get started extending CiviCRM.
The first sprint laid a solid framework for the book, but there were definitely some rough edges and some gaps that needed filling. At the second sprint, we filled and smoothed, completing coverage Civi’s components, revising already existing sections, adding the developer section, and finalising a section template that we can use for covering new functionality like the upcoming CiviCampaign.
The second book sprint was held at the same time and place as a code sprint. Each sprint was self contained but we met in the evening to eat and to swap in and out of different sprints. All in all there were about 30 Civi folks gathered together. Having such a wide range of talents in the same place was quite awesome and led to some unplanned beneficial cross overs. Usability and naming improvements made their way from the book sprinters into the code sprint and book sprinters documented new functionality as it was being developed at the code sprint.
Public reactions
I proudly showed the printed second edition to people at a non profit tech conference a couple of days before the training. While most people reacted positively, I was suprised by a couple of the reactions I got. A couple of people, rather than being impressed with the thickness, found the book a little intimidating. It is worth noting the difference in perspective: one person’s “wow, that is a comprehensive book!” is another’s “wow, that is complicated software!”.
Which brings us nicely on to our plans for the future...
The future
One of the aims of next years book sprint (funding permitting) will be to split the single volume into a number of smaller books. From a content point of view, this shouldn’t be too much of a challenge. Each section already follows a pretty well defined structure (with introduction and chapters on planning, configuring, everyday use, etc.), so the comprehensive guide can become Everyday CiviCRM, Planning with CiviCRM, etc. From a technical point of view, the new Booki authoring engine should allow us to link the same source chapters into different books. As well as cutting down on maintenance, this should be a good discipline for ensuring the right content is in the right place, and that we really are being comprehensive.
As the book has become more mature, we are begining to wonder about the relationship between the book and the wiki. We are seeing more and more people link to the book from the support forums. And this raises the questions: What belongs in the wiki and what in the book? Where should I document this new bit of information? Is the book just a more stable version of the wiki or do they cater for different audiences? Is it OK for us to copy from the wiki to the book and visa versa? I don’t think we have clear answers to these questions yet but we should probably come up with them soon.
Another question we are condisering is distribution. The new version of Objavi gives us a few options that we didn’t have before. We currently host the book at http://en.flossmanuals.net/civicrm, but we could now easily export templated HTML to http://book.civicrm.org. We could also look at including the book with the download (compressed and without pictures it is only 406kb). And we can even click to make an ebook version. Very cool!
So dig in and edit and improve the book! And let us know your thoughts on what you'd like to see in future versions. Suggestions and ideas for future sprints are welcome here or in the documentation forum: http://forum.civicrm.org/index.php/board,11.0.html
Comments
Including the book with the download is a great idea!
Thanks for a great post Michael and thanks for all your work on the manual etc!
Funny (but understandable) that people both complain about the lack of documentation for Open Source software generally, but then they (or others) complain when the documentation is too voluminous!
I think the book and the wiki should cater for different audiences, and perhaps one way to address the concern about the size of the book is to have less in the book and have references to the wiki for more information on specific areas in the book. As CiviCRM is an online tool that is often configured very specifically to a client's requirements, I think a lot of the "administration guide" and advanced "user guide" type information is most relevantly in the wiki, while the book can focus on general understanding of CiviCRM, how it is fundamentally different from proprietary platforms and explaining how to use the core functionality within a standard installation. To this end, perhaps a lot of the "Planning" and "Configuring" sections could be in the wiki or an Administrator version of the manual, and a configuration checklist in the "book" that refers back to the wiki/administrator manual could be sufficient, then the rest of it can be focused on general use (ie "Everyday Tasks").
I don't think putting a templated HTML version of the book at http://book.civicrm.org would provide much added value as it would distract people from the fact that they can get the pdf version and/or print version easily too (which many people still like to have for "getting to know you" documentation about a software platform) and may create increased confusion between book/wiki. There is then also the maintenance issue if it is in two places.
PS - there is a typo in your link to the book, it should be: http://en.flossmanuals.net/CiviCRM
Andrew
Community Builders Australia
Can't we push the idea that people can re-mix the book for those who find it too much?
Hey, two of the authors discussed doing it, and we haven't yet ;)
In conclusion, we might have to push quite a bit to get there.
X+
I think that if the book is intimidating, then remixing it to make a smaller version is more intimidating :)
from experience it seems that outside the sprints, it is hard to do big chunks of work like creating remixed books. never say never of course but that is one of our aims for the next sprint. and fingers crossed this will be easy to do with new booki :)
Thanks for the typo notice, fixed. And good thoughts on wiki vs book - we need to keep this discussion going and make some steps soon, otherwise we'll end up with a lot of duplicate content to maintain.
The book is great, and the chapters on extending have been a good help for me. Reflecting back on that with the book/wiki thing in the back of my mind:
I was quite happy with the information in the wiki, but it seems that I have to know what I am looking for when I go there. For example, if I want to know how to use the contact API I can find it (more or less :-)) on the wiki. What was not in the wiki was the overall concept of API, how this works in general and when to use it. This I found in the book.
So: background, concepts, stories that try to reach out to users, new administrators and new developers I would expect to see in the book. Detailed information where I know what I need to ask, I would explect to see in the wiki. Does this make sense?
I think that is a really good way of distinguishing between them. Releated to that, I also like the book should be finished, wiki is OK to be a work in progress idea.
Where is the best place to order a hard copy of the book?
http://www.lulu.com/browse/search.php?fListingClass=0&fSearch=civicrm is a good place to get one. it's not the absolute latest version but there is little substantive difference...
We should likely distinguish between the Documentation that is provided for each version on the wiki (http://wiki.civicrm.org/confluence/display/CRMDOC32/CiviCRM+Documentation) and the developer documentation on the wiki (http://wiki.civicrm.org/confluence/display/CRM/CiviCRM+Wiki). There is a bit of overlap in purpose and content between the Documentation wiki and the book but not between the book and the current and proposed projects on the developer wiki. So let's ignore the developer wiki in the current discussion.
The documentation wiki came first and the book came later. The wiki was a place that mixed user, admin, advanced admin, and developer material. There was spotty overview material. The wiki's organization and content has improved over the years.
The book was very good for giving context and for supplementing the Documentation wiki with longer sustained treatments of topics. It is currently better for getting an overview of most non-developer things in my view. The wiki has a broader range of specific topics, and an organization that is oriented a bit more to explaining how to do things on ever page and form in the system. Ideally, there should probably be some better integration between the help provided in the software and the wiki pages. The former are really coming along well.
As mentioned, there is some overlap at present between book and wiki particularly on user interfaces and recipes which increases the maintenance workload.
So far my sense is that the book has not been getting updated as continuously as the wiki.
I see the book and wiki serving different purposes and can't see an easy way to integrate them.
As many people know, there will be a new CiviCRM book co-authored by Brian Shaughnessy and myself appearing early in the new year. I expect that as the community grows there will be a need and market for more approaches and more specialized material. For example, the growing number of Drupal books is a testament to as well as contributor to the growth of that open source project.
The wiki is a good place to provide more examples, tips on experimental features and anything else that should usually be verified and cleaned up before going into a book. So I would agree that the book is a more stable version of the wiki, but also that the wiki is for a more geeky audience. I check the wiki mainly for developer information.
As for the size of the book, I have a copy from Lulu.com: it may look big (although I disagree, it's equivalent to most computer books), but the font size is big, there are many blank pages (between sections) and the credits pages are quite long. The only content I could imagine in another book would be the developer docs or advanced system administration, where we could eventually add chapters on performance, scaling, large scale civimail, etc