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 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:
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...
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.