FLOSS Manuals

 English |  Español |  Français |  Italiano |  Português |  Русский |  Shqip


BookSprints: CiviCRM


This book sprint was a week-long event, preceded by considerable planning, that took place in a resort area near Lake Tahoe, California from May 3-8, 2009. This sprint resulted in a book of approximately 280 pages that was highly regarded by the community.


The CiviCRM project and community

CiviCRM is a free CRM projects. There are many free software projects in this space, but CiviCRM is distinguished by its focus on non-profit, government, and advocacy sectors. They prefer to use the term Constituent Relationship Management for CRM instead of the common expansion, Customer Relationship Management.

CiviCRM's documentation is typical for a free project, though probably somewhat superior. They have tutorials and examples, along with complete reference documentation. Community forums are active. One factor that put their educational resources a notch above most projects is a collection of test sites where you can practice your skills as a CiviCRM administrator without first installing it.

Nevertheless, the CiviCRM leaders felt a need for improving their documentation. They decided to hold a sprint in San Francisco and to fly Adam in to lead it. They also agree to pay Andy to provide organizational and editorial support.

Platform Development

For this sprint Aco developed a feedback mechanism which would send notifications to the FLOSS manuals web chat when someone started editing a chapter. The feedback is italicised and looks like this :

AdamHyde is editing BookSprints - FLOSSify.
AdamHyde is editing BookSprints - CaseStudyFour.

This has actually proven more useful for non-sprint days as it is possible in real time to see who is active in FLOSS Manuals editing manuals other than the one you are working on.


The division of labor between Andy and Adam went well, except for one issue that fell through the cracks, as we'll see. Adam, who has had more experience than anyone leading book sprints (although he still feels he's experimenting a lot, and may always experiment a lot), explained the process to everyone and came to San Francisco to be Sprint Master. Andy did not travel to San Francisco, but put in over fifteen hours beforehand mobilizing the community and leading discussions related to content. Andy also did substantial editing during the sprint.

As with most sprints, pre-planning was concerned with three tasks (aside from logistics such as food and accommodations):

  • Determining the scope and topics. This proved more difficult than with most sprints.
  • Developing the outline, which required recruiting and motivating subject matter experts.
  • Recruiting authors.

The pre-planning started with productive discussion on a mailing list set up by CiviCRM explicitly for the sprint. Members were added to the list by invitation. In addition to Adam and Andy, it contained about a dozen people with extensive experience deploying CiviCRM in their own organizations and as consultants. They had tremendous experience and lots of ideas about what's missing from the documentation. Their suggestions were deep: how to prepare your organization, how to map your current practice onto CiviCRM, etc.

However, the group needed coordination. There was too much centrifugal force during early discussions; nothing was coalescing. The mailing list members discussed whether the audience should be end-users, administrators, advanced programmers, or outsiders interested in learning what CiviCRM had to offer. They considered nitty-gritty administration books (particularly on advanced topics) and very high-level, conceptual books. They debated different ways to incorporate case studies.

All these ideas were good; the question was which to do for this sprint. Andy kept them talking, told them to write down ideas, and tried to formalize what they wrote so it looked actionable.

Eventually Andy realized we should have a vision statement. This might sound like overkill for a sprint, but it seemed useful as a way to anchor the group and give them a guide so they could prioritize. Andy summarized the trend of the conversation, but there was no real work on the vision statement and it didn't prove useful when a quick decision was needed later.

A teleconference lasting more than one hour was also held about ten days before the sprint. Half a dozen CiviCRM leaders joined in, along with Andy (Adam, unfortunately, was not present) and a great deal of progress was made in defining CiviCRM's needs and dividing up tasks before the sprint.

Up until that time, project members were reluctant to add to the outline. Ideas flew back and forth on the mailing list, and Andy added what he could derive from this discussion to the outline page, but it wasn't developing. In fact, it took some effort just to persuade project members to sign up for FLOSS Manuals accounts so they could try out the software and edit the outline. Some people submitted stubs for case studies, but there was little material in them.

About two weeks before the start of the sprint, the team was uncertain of what to do and whether they were going in the right direction. Adam had to reassure them that things are normally open-ended and that the sprint itself is the only place to resolve a lot of the issues.

But thanks to the mailing list discussions and especially the teleconference, momentum picked up. A week after the teleconference, the outline was not only quite large but well organized. There seemed to be a sense of "we're cookin'" and "we can do it."

It should also be noted that, even though we spent much more time planning the sprint than most projects do, some participants wished we had done more.

Controversy over outline

So in one week we went from too little to too much. Having participated in only one book sprint (an unusual one, the Command Line book) Andy didn't recognize that there were several times too many topics in the outline to write about in one week. About a week out from the sprint, Adam recognized the problem and decided to cut the outline way down.

In retrospect, we couldn't see any way to hold back contributions. Andy needed to take strong steps during the weeks before the sprint to encourage contributions to the outline. Once you open that spigot, you can't turn it off without sounding discouraging.

As mentioned, Adam had actively decided not to participate in detailed discussion of the outline and leave this to Andy--although Adam was on the mailing list--and was not part of the teleconference. Andy had been intensely involved, but didn't have enough experience to size the outline.

Adam presented the truncated outline to some CiviCRM community leaders the week before via email and at a real space meeting, however they rejected it.

Adams approach was then to re-open the discussion about the outline on the first day that everyone arrived at the sprint. The sprint team quickly created an outline, with Adam playing a facilitator role, so we got over that mini-crisis. Interestingly the outline created by the CiviCRM team on site at the sprint reflected almost exactly the outline Adam had presented a few days before.

Sprint-week editing

The team worked very hard during the week, often logging in early and staying late. Like all sprints, the level of professionalism in the actual writing varied, but the ideas were almost 100% on target (and the things that were inappropriate for the book got weeded out).


Andy edited a few chapters very early in the week to set professional expectations for pace and style. Most of his questions were along the lines of: "does the audience need this?" and "what's missing?" Andy also put in most of the day Wednesday on editing.

By Friday, the team decided to concentrate on filling in gaps and polishing what they had done the rest of the week. The finished at 6:00 PM and published the book. 260 pages - our biggest yet.


During the week we also managed to get out a bit and have some fun!



The book was considered a success by CiviCRM leaders. The usual clean-up was performed in the following few weeks. Two sprinters noticed that some of their material had been removed late in the sprint. There is still discussion about where this material could fit in to the book. We believe a long-term maintainer has also been found.

In addition, the FLOSS Manuals editing interface has been slightly simplified to avoid the temptation by contributors to over-complicate the layout which occurred a few times during this sprint. The layout has to be kept simple so the material is rendered well in both html and pdf formats. This will be less of a problem in the future as FLOSS manuals has developed a more complicated PDF rendering engine that supports the full spectrum of CSS layout, so a more complicated WYSIWYG layout may be an option in the near future.


Some feedback sent in by the CiviCRM Sprint participants after the book had been out for a few weeks :

"I received the following feedback from a potential CiviCRM user who was reading our book. She had some basic questions and she used the Organization information in the Examples section to send an email to the AFSC's general information address. That email was forwarded to me.

After I answered her questions, giving CiviCRM glowing reviews of course J I asked her what she thought about the book. This is what she said:

'And I would like to say, if by book you mean the website http://en.flossmanuals.net/CiviCRM, I thought it was very helpful and really well organized so wonderful job there'.

When I read her comment I immediately thought of all of you and wanted you to be a part of what I was feeling, which was pretty proud of all the work that we did. It feels really good to know that people are
actually referencing it and that at least for some, it is helpful. "

Cynthia Tarascio, Book Sprint Participant


"I've also gotten some very positive feedback from folks on IRC. We are frequently referring folks to it on the forum when it's clear they need "the big picture".

Dave Greenberg, CiviCRM founder and sprint participant


"I actually received some feedback recently that I’ve been meaning to send out to the group. I was contacted by someone who was in the process of implementing Civi and needed some assistance (he’s already begun implementation). He mentioned having read significant portions of the book, and was particularly impressed with some of the early chapters that dealt with project management, identifying key players, etc. He said he took a step back to rethink how he approached some aspects of
the project after reading those sections."

Brian Shaughnessy, Book Sprint Participant


"I met someone from Greennet recently (an ethical UK ISP) at a London Net Tuesday event.  He was a developer who was doing his first development with a client and said he found the book super useful in
getting to know the system.  He said that he learnt loads about Civi through the book and was really grateful to have access to it.

I've also seen 3 copies of it out and about on my travels - and watched 2 people buy it online (and I didn't pressure them into buying it - honest!)"

Michael McAndrew, Book Sprint Participant and Manual Maintainer


"I met with the IT manager of a (new zealand) political party today who was considering CiviCRM. He contacted me through the Circus Trust as he had read the case study.

Anyway, he was really positive about the book and made the comment that 'IT manuals normally put him to sleep but this one was interesting and well-written'. It was obvious that reading the book was having a significant influence on the likelihood of him going down the CiviCRM path and also increase the amount of functionality he would take advantage of.

So, nice to see that not only do people appreciate the book but that it also achieves it's goal of getting people to use Civi & to use it better."

Eileen McNaughton, Book Sprint Participant

There has been error in communication with Booktype server. Not sure right now where is the problem.

You should refresh this page.