A new home for our documentation

We've built a new home for CiviCRM's documentation. Here's a quick run down of what we've done, why we've done it, and how you can help with the move.

First, a quick recap of our documentation's long and illustrious history:

Pretty much all our documentation started long ago on our trusted wiki. Our wiki is great, but like all wikis, a bit messy and a bit incomplete.  A few years later (starting in 2009) a concerted effort was made to 'finish' our user documentation - to write a complete book on how to use CiviCRM, the result of which was the CiviCRM user guide, hosted on a different platform: Flossmanuals. Flossmanuals was very good to us. We were able to complete a book that covers pretty much everything that you can do via the user interface, which was a big step forward. And it got us in the habit of running one or two books sprints a year, which has enabled us to keep our user documentation up to date with each release (woo!). But Flossmanuals has had some issues - it hasn't been available 100% of the time, and it is primarily aimed at printed books, which limits us when it comes to simple things like creating links, and also prevents us from adding more complex formatting (useful especially in developer documentation). So we decided to look for another platform.

It took a while but eventually we settled on the amazing readthedocs.  readthedocs is more than a documentation platform - it's also a set of well thought out conventions to follow. This makes it great as simple and stable base for our documentation. It's plain text files written in markdown* and stored in a git repository (e.g. the user guide is here: https://github.com/civicrm/civicrm-user-guide). There are lots of options for editing: directly on github; locally with your favourite text editor; via a command line tool; or with any number of (yet to be invented) user friendly web based user interfaces. You can also publish your documentation at readthedocs.org but we aren't using their hosting. We are instead using a readthedocs publishing tool called mkdocs to publish our own domain: http://docs.civicrm.org.

We decided to host our own for a few reasons:

• we have a fairly large set of documentation (lots of topics to cover and different audiences to cater for) and wanted to have control over how all our books are organized
• we do a lot of linking from the UI to our documentation and its helpful to have full control over URLs for redirects, etc.
• readthedocs does offer a lot control over formatting but hosting our own gives us some more options and flexibility.

We currently have one book in the new format - the CiviCRM user guide. Our hope is that now we have a stable platform, we can start to migrate more documentation from the wiki. Our long term plan is that the wiki will cease to be somewhere to go for documentation (though it may still be used for other purposes, e.g. writing specs, documenting the roadmap, etc.) and that all documentation (including developer documentation) will be available at docs.civicrm.org/

Here's a run down of we are organizing documentation:

• http://docs.civicrm.org is the documentation home page, presenting all available books (only one so far!)
• books are be accessible at URLs as follows: http://docs.civicrm.org/user (or in the case of extensions http://docs.civicrm.org/extensions/civisualize)
• languages for each book can be found in language subdirectories, e.g. http://docs.civicrm.org/user/fr
• versions for each language can be found in a further subdirectory: http://docs.civicrm.org/user/fr/4.7

Each language of a book maps to a github repository and versions for that language are found in branches of that repository. Merging a pull request on a branch of any repository will automatically update the published version of the documentation. For more details on how this works, have a look at https://github.com/civicrm/civicrm-docs/. If you're familiar with readthedocs, you'll notice that we haven't re-invented anything new here - we're just following readthedocs conventions.

One great thing about having your documentation stored in a git repository is that it can be the same repository that you are using to store the code, which allows you to update the documentation in the same pull request that contains updates to the code.

That's probably enough about how it is all set up. Now on to how you can get involved...

• Want to contribute to the CiviCRM user guide? see https://github.com/civicrm/civicrm-user-guide for instructions
• Want to translate the CiviCRM user guide to your language? Get in contact with me (michael@civicrm.org) and I can get you going.
• Want to document your extension? You can do so by following instructions here: https://github.com/civicrm/civicrm-docs. Since you'll be a trailblazor, it would be a good idea to email me so we can make sure that the URL structure is working, etc.
• Want to help out with the documentation infrastructure? here's a list of todos: https://github.com/civicrm/civicrm-docs/#to-do. A couple of items from that list that I think are worth highlighting
  • enable the creation pdf and ePub versions of the document when publishing (maybe using pandoc)
  • find a nice user friendly UI for people to edit the documentation (the github UI is OK but we can do better)

Finally, in case you're wondering, docs.civicrm.org will be available via https imminently.

* You can use two text formats in readthedocs. markdown and restructured text (rst). rst is a more sophisticated format than markdown but also harder to get to grips with. Since we don't think we need any of the sophisticated bits, and since markdown is much better understood and is more approachable, we went with markdown.