System Administrator Guide completed

2017-11-14 20:17
Written by

Two months ago, I launched a Make It Happen campaign to build a System Administrator Guide with the goal of migrating the installation, setup, and upgrade documentation out of the wiki and into a beautiful guide on our new documentation platform. Amazingly, the MIH campaign reached its $2,000 USD minimum in only 4 days — which meant I could get to work right away!

Now I've completed this content migration and am excited to share the System Administrator Guide with you, in all its glory...


Before you thank me, join me in thanking these partners and community members who made this project happen by backing the campaign:

Each of these backers made an investment in CiviCRM's documentation, and this investment will continue paying off (for all of us!) by saving system administrators valuable time when maintaining CiviCRM installations. Thanks!!

Current status and next steps

Now we have a System Administrator Guide!

But of course, it will never be "done" — it will be a living document that many community members will continue to shape for years to come. For the purpose of completing this Make It Happen project, I had to draw the line somewhere and call the project "done". From the start, the goal of this campaign has been to migrate existing installation, setup, and upgrade content from the wiki into guide. But the line around this goal is definitely a bit blurry. So I want to be clear about where I'm stopping...

Things I did

Aside from the essential work of migrating 82 wiki pages, here are some additional improvements I made along the way:

  • I massively improved the "scheduled jobs" documentation, both in the Sysadmin Guide and in the User Guide.
    • Content in the User Guide is now better targeted towards users who are likely to begin reading the Scheduled Jobs page without any understanding of what "cron" or "API" mean, and who don't have access to do things like setup cron or create a site key. It also explains quite a bit more about how scheduled jobs work and comprehensively documents specific jobs along with their available parameters.
    • The two separate pages (in separate guides) are mostly mutually exclusive and link to each other to aid discoverability.
  • I did major cleaning of all the installation and upgrade docs to make the pages shorter, simpler, and easier to follow.
  • I created a new requirements page, separate from the installation and upgrade pages.
  • I consolidated content on tokens which was spread across all three guides, and put this content into the User Guide.
  • I migrated several other small wiki pages to the User Guide on dates, addresses, mapping, users and contacts, resource urls, and error handling (after initially thinking that they might fit well within the Sysadmin Guide).
  • And I did lots of other small things too, some of which are captured in these closed milestone tickets.

Things I didn't do

On the other side of the blurry line, here are some outstanding tasks which have fallen just slightly beyond the scope of the project, as I've chosen to define it:

There are plenty of other open issues as well, but I chose to highlight the two above because they're things I could have reasonably defined as part of this project but chose not to. Gotta draw the line somewhere! I see these tasks as the highest priority work that needs to happen on the Sysadmin Guide right now.

It's also worth pointing out that other people have already jumped in and have been helping out with the Sysadmin Guide. In particular,

Reflections on our Make It Happen model

Make It Happen is awesome. It worked splendidly for me, and I want to help grow the MIH model among our community. Do you have an idea for a Make It Happen project? I would love to help you get it off the ground! Find me on Mattermost and we can chat.

After all we make fundraising software, so I think we have huge opportunities to do more fundraising for improvements to our product!


Awesome work Sean (and team!). I've already seen some of the new pages and it's like a breath of fresh air. Thanks for pushing for it to be better, we all benefit!

Thanks so much for doing this Sean.   This is a big improvement to the documentation.

All of the new docs you've 'Made Happen & have spent so much time on are a magnificent resource for the CiviCRM community and all it's stakeholders. This is something that we have needed for a long time.

Thank you to all involved for the hard work & resources to get it done, and for the approach that ensures that it's so easy to maintain, too.