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... **** ## Thanks Before you thank *me*, join me in thanking these partners and community members who made this project happen by backing the campaign: * [Nubay Services]( * Seamus Lee * Eileen McNaughton * [Cividesk]( * [JMA Consulting]( * [Fuzion]( * [AGH Strategies]( * Tim Otten * [Megaphone Technology Consulting]( * [Compucorp]( * Brian Shaughnessy * [Lemniscus]( * Craig Luchtefeld 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: * I didn't [migrate wiki content on internationalization and localization]( * I didn't [clean up CiviMail docs]( 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, * **Herb Dool** [added]( new docs on [upgrading CiviCRM within Backdrop]( * **Jon Goldberg** made [significant improvements]( to the [troubleshooting]( page. * **Alan Dixon** updated the [iATS]( and [Moneris]( info. * and [8 other people have made small commits]( ## 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.