Skip to end of metadata
Go to start of metadata

We will be holding a Book Sprint from April 23-26 to develop a new edition of Understanding CiviCRM - the free online CiviCRM book. We'll use page to collect general ideas on ways to improve the book.  Chapter specific comments should be added directly to following
the basic convention of: COMMENT INITIALS: text in bold italic

If you're attending the sprint, please edit the page directly.  Otherwise, please feel free to comment and we'll incorperate your comments into the text of the page.

Ideas to improve workflow / not make the same mistakes we made last time

communicating with people in the room

Using the IRC and talking to each other during the sprint is a great idea and really necessary.  There are a few sections in the current book which repeat stuff that is covered elsewhere.  Whilst in some cases this makes sense, it doesn't always, and it's really good to ask people (using your mouth or using IRC) if what you are about to write has already been written somewhere else, and discuss the best place to put stuff.

Before you start reviewing a chapter, and before you start making big changes to a chapter, talk to the person that wrote it / last edited it.

Images workflow

Would be great to set up a demo site that we can use to pull all images from, and have someone in charge of creating those images, and making sure that the data is there to create the images from.

working with andy

Working with Andy Oram. Andy is an editor with O'reilly and gave us lots of useful feedback on the book last year.  There were some co-ordination problems because Andy was working remotley.  We think we can solve these by having a more formal structure for Andy's contributions.  One solution could be: at a set time each day, we work out what we'd like Andy to focus / look at. Andy goes away and looks at these areas and feeds back to us the next day.

keep formatting simple

Lets keep formatting as simple as possible.  As Adam says, there are complexities when it comes to exporting to different formats, and the tools we are using to create the book aren't able to handle complex formatting.  It's much easier to keep everything as simple as possible, rather than slightly complex with each person presenting things in a slightly different way.

Summary of feedback on the Current Edition

Structural changes to the book


MM: These section headings are very cryptic and the content in them needs some sorting out.

I propose that we merge them and rename them Planning your CiviCRM project with the following chapters:

  • Is CiviCRM for you?
  • Project management  (planning, project team, Decision Making Process, Take advantage of institutional knowledge, Technical and logistical planning, Establish a budget for your project, Identify support needs, Identify support needs, One Step at a Time,
  • Your requirements (constituent-centric organization, organisation processes, Define the desired set of constituent experiences, Examine organisational goals and practices, What functions must your new CRM system address? Identify repositories of data, Identify the information that you wish to collect and track, Identify the staff who will use the system)
  • Modeling your data (Thinking About Your Data)
  • Technical requirements (Identify the hardware/browser that will be used by office staff, hosting)
  • Installation

Structure of the component sections and chapters

[todo: how can we improve these to reduce repition?  are there parts that we can pull out at put in a working with CiviCRM chapter, explaining basic workflows like "the searching and more actions workflow", for example?

The concepts section

MM: This is a pretty vague name for a section.  And there are some parts that don't fit here, like Who is CiviCRM.  We could potentially move

Getting around CiviCRM

This might be a nice place to store chapters about workflows (i.e. searching and editing).  The the contact summary screen.  And also about the idea of components.

Style / general improvements


Chapter headings

User feedback suggests that it is hard to find what you are looking for in the manual.

A client of MM's said "I had a thought about the Civi guidebook - it could really use an index at the back. So, for example if you want to look up 'adding contacts to groups', you can go straight to the index and find the exact pg number rather than having to search through the whole groups chapter. I know there's a table of contents at the front, but I don't think it's detailed enough."

Maybe an index isn't feasible but we should look at how we can make things easier to navigate.

I think we should make our chapter and section headings more straight forward and more closely linked with CiviCRM concepts to help with this.  For example, we could have 'Using profiles to collect and share information' rather than collect and share information, and CiviMail rather than Emailing people.

We could easily call the later sections after the module name and then give explanatory chapter names, i.e.

Section: CiviContribute


  • Planning fundraising
  • Managing your fundraising
  • Reporting on your fundraising

Also, can we avoid one word questions like "CMS?" and "Constituent?"

Less kool aid drinking / marketing speak

We should do less cool aid drinking and concentrate more on getting the message across on what it can do.  Marketing speak hides the point.  This book isn't an advert and some of the more flowery language is unecessary or hides the point you are trying to make:

Some examples...

Find: "CiviCRM has a sophisticated finance and fundraising framework" Replace: "CiviCRM's CiviContribute component is made to assist with fundraising, and any aspects of CiviCRM that involve a financial element (e.g. paid events, paid membership, etc.)" .  You could replace with

Find: "CiviCRM offers the entire spectrum of all the abilities of CRM to engage your constituents" Replace: nothing (smile)

Find: "It also allows you to quickly and easily create customized web pages" Replace: "You can create customised webpages"


We made a few diagrams last time that didn't find their way into the book.

Version agnosticism

Where possible, keep text as version as agnostic as possible

No pop out boxes

Last time we had some discussion about if and how we could use pop out boxes.  These didn't work that will in practice (when it came to publishing the book, etc).  We should remove ths CSS styling for these boxes and  (they don't render well in print and are liable to get confused when others make changes to the book. Instead, we can agree on some header prefixes, like *"Note: **",* and *"Case study: **"*

Introductory paragraphs

We are missing a lot of  introductory paragraphs, which are important to guide people through the book, and let them know what is in the chapter. Sometimes the introductory chapters give nice background to a subject which is important, but there should be a paragraph before that which outlines what is covered in the chapter and then do the content of the chapter.
For example, in communicate more, it starts "Good communication is all about knowing your constituents.  An integrated, historical record of interactions with each constituent means you have detailed knowledge that you can use when you talk to them on an individual basis."  But we should outline here what Civi does with communication first, and then say that it's better to do that within Civi because you have access to all that knowledge"

We don't need to be so conditional

We should accept that not all organisations will want to make use of all functionality and don't need to spell out that all info won't be of use to all orgs.
Find: "Depending on the activities and services your organization is involved with, CiviCRM can provide you with tools for donor management, memberships, event management, email and postal communications, tracking services and reporting. For advocacy, non-profit and non-governmental groups, this often adds measurable value."  Replace: CiviCRM provides you with a set of tools for donor management, memberships, event management, email and postal communications and more - the kind of things non profits do on a regular basis.  Taking advantage of this out of the box toolset can add great value to your org.

Invitations to get involved

It would be nice to pepper the book with hints and suggestions about how people should get involved - to re-inforce the community nature of CiviCRM and include lots of "this would make a great community contribution" type statements.  These might be  via case studies of how people have got involved.

New chapters / new functionality to cover


  • Who this book is aimed at - what is / isn't covered.  Where else you should go for help

Core functions

  • Context menus / 'new ...' dropdown'
  • Search configurations
  • Additional dupe merge options
  • Home dashboard / dashlets
  • Navigation menu
  • Contact subtypes
  • The 'search then perform action' workflow
    eg: How to changes on hold email to active?
    How to delete/ update null contacts from my db?


  • System workflow message templates (for sending contrib receipts, event confirms, etc.)
  • Multi-language sites
  • Multi-site / hierarchical org configuration and use ( we might want to skip this - kurund )
  • Theming system-generated email (i.e. message templates for contribution receipts, event confirmations, etc.)
  • Address parsing


  • Pricesets


  • Personal Campaign pages - configuration and workflow
  • Price sets




  • Event templates
  • Waiting list management and moderated event registration workflows
  • RSVP Events/Name badges (3.3)


  • Best practice for sending email / avoiding spam
  • Managing bounces


Creating and customizing reports (intro w/ examples)

Should also be flagged up in modules


  • Features / use-cases
  • Configuring CiviCase
  • Using CiviCase


Customisation and development

  • Using hooks to extend and modify CiviCRM (intro with examples)
  • custom templates
    may be bit intro to smarty??
  • Public API's
    REST AJAX interface
    Calling API's in template using crmAPI

Chapter specific comments

*Please add chapter specific comments directly to the basic convention of :*COMMENT INITIALS: text in bold italic

  • None
  1. Mar 25, 2010

    CiviMember - Good explanation of CiviMember expiration date rules, with multiple examples. The book and wiki are both lacking here. This should include not just new memberships but renewals as well, as the rules do not behave the same on renew as they do on a new membership. An example explaining how to extend expiration to the end of the month would be useful. Since most memberships are not sold in January for many organizations, the January-December membership examples only serve to confuse in some cases.

    CiviMail - Configuring CiviMail Settings is a copy/paste from the wiki, which is itself quite confusing here. This section makes assumptions that the book's audience knows intimate details about mail server configuration and the field explanations are terse. A solid example or advice on setting this up for two or three popular web hosts would be very helpful.

    Payment Processing - The Fundraising Planning section touches on this briefly, but doesn't walk the reade through setting up a payment processor. The book could go with Pareto on this and take the user through setting up the two or three most popular solutions.

Creative Commons License
Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-Share Alike 3.0 United States Licence.