Revamping CiviCRM Documentation

We are four days into the sprint now and things are going great! I think everyone was ready to get right to it this morning since the crew got to sneak away yesterday for an afternoon out at Lake Tahoe. The breath taking view from Eagle Rock was a great way to regroup and get ready for the remainder of the week.

For the last few days Team McAndrew, led by none other than… you guessed it, Michael McAndrew has been focusing on revamping the documentation in preparation of the 4.5 release. A snapshot of new documentation includes:

  • New “In Honor of” or “In Memory of” soft credit functionality
  • CMS specific documentation including Worpdress Shortcodes and Joomla! Menu item types
  • Reworked explanation of scheduled reminders
  • Using tokens with custom fields
  •  And much more about new features in 4.5!

As we are winding down on documenting some of the new features, our group had a discussion about reworking the structure of the book to make important items more accessible and easier to find. So we are going to give one of the sections a go. As a group we decided to start with Memberships.

As a background here is a current structure for the Membership section within the User and Administrator book:


  1. What is CiviMember
  2. What you need to know
  3. Set-up
  4. Everyday tasks
  5. Reports and analysis

We decided that none of those chapter titles really gave you an idea of content that existed in that chapter. So, after a bit of mind mapping this is the structure that Alice, Joanne, and Michael came up with:


  1. Introduction
  2. Defining your memberships
  3. Online membership signup
  4. Manual entry of memberships
  5. Finding memberships
  6. Membership Reports
  7. Renewals
  8. Canceling and expiring memberships
  9. Membership websites

Each of the chapters will have subsections that dive into the weeds with the day-to-day administration of CiviCRM. We are hoping that end users and administrators can get to the information that is relevant to them much quicker. Feel free to give us some feedback when you go through the new section!

During the same discussion of reworking the structure of the book, we had another idea surface that we think might bring additional value to end users, administrators and CiviCRM evaluators. The idea started by discussing the lack of relevant use case data within the demo environments that inquisitive end users can relate to for their specific organization. As of right now we have some basic events and contribution pages set up, but what if we had a series of environments that were catered to a specific use case, and then that use case was referenced in the user and admin guide and then on top of that we had a workbook that enabled, end users, administrators and evaluators to configure this specific use case from start to finish within their own CiviCRM testing environment? Sounds pretty awesome huh? At least we thought it might be cool. Our goal would be to create some cohesiveness throughout all of the enablement material. Of course to test it out we are going to start with one use case, see how it goes and then build additional options from there. This sub group of the documentation team decided to go with Memberships as well. We are building out the scenario/narrative right now that would give a membership based organization something to relate to. After that we are going to start building out the workbook that would take someone end to end from defining membership types and payment processors, publishing the contribution page for membership all the way to reporting on lapsed members. After that, who knows, maybe we will get to build out an instance of CiviCRM with a sample data set to use in the scenario.   We will keep you posted!

Image icon EagleRock.JPG78.49 KB


As a Software-as-a-Service provider, a lot of the support questions we do get are on the subject of membership renewals.

In particular:

  • when doing a membership renewal campaign, you need to remember to insert a checksum token in the link to the membership renewal page. This way the renewal page is pre-filled when your members click on the link.
  • when receiving a check they have to be careful not to use the online renewal page to enter the renewal, but instead use the 'back-office' administration screens.

Both of these 'gotchas' often greatly confuse our customers. All-in-all, I would think that membership renewals deserve a sub-chapter on it's own, just like your subchapter 7.

Great feebdack. I just looked at the mindmap again and renewals actually does have a chapter of its own... I just accidently left it out. I will be adding it in now. Thanks for the find!