Experiments with read the docs

A while ago I did a test migration of CiviCRM's user and admin documentation to gitbook and said that I'd also do a migration to readthedocs so we could compare the two.  I finally got round to completing the readthedocs migration so wanted to share with you some impressions so far, the advantages and disadvantages are of both systems.

Spoiler alert: At the moment, I think we should go with readthedocs. If you're interested in the reasons and the gory details, keep on reading - I would love you have your thoughts and opinions.

Most of the work consisted of creating a script to convert from gitbook to readthedocs. It's not pretty but it works and means that if we decide to go with readthedocs, it will be simple for us to convert the latest gitbooks version over to readthedocs (and that we can continue editing the book in gitbook format until we make a final decision).  Here's the script in case you are interested: https://github.com/michaelmcandrew/gitbook2readthedocs.  All it does is create a mkdocs.yml file to define the book's structure and put the chapters into the directory structure that readthedocs is expecting. The end result is currently here:

You can see the results here: http://civicrm-user-guide-rtfd.readthedocs.org/en/latest/.  There are a few rough edges (the search isn't working, the edit links don't quite match up with github, but it should give you a good idea about what the documentation would look like with with the default readthedocs theme. The source code that produced this is here: https://github.com/civicrm/civicrm-user-guide-rtfd.

Editing interface

One of the big selling points of gitbook is its simple web-based editing interface, which amonsgt other things, hides the complexities of git from non technical and one time contributors (git is fairly intimidating to the uninitiated after all). Gitbook is definitley ahead of readthedocs in this respect.  Having said that, one of the reasons that we've chosen the git and markdown combination is that it means we aren't tied to a single editing interface - people are free to choose a set up that works for them - and the pace of development of markdown and git based editors is pretty rapid, so I can't imagine it will be long before something like the gitbook UI is more widely available.

In the mean time, github itself offers a fairly easy to get to grips with option for editing single files directly in the main repository, with the following steps.

1. Visit https://github.com/civicrm/civicrm-user-guide as a github user (that doesn't have write access to the repository).

2. Hit the edit icon and make the changes you want.

3. Submit your changes. This automatically creates a pull request from the branch that you were editing (most likely master) which can be reviewed by someone with write access to the repository.

Some things that are missing from this - most importantly, the wysisyg experience. But on the plus side - github has a markdown preview built in and doing pull requests directly on master means that first time editors don't have to think about branching or merging.

Versioning and translation

One plus for readthedocs is well thought out framework for versioning and translations, specifically designed for software documentation.  We can have the book point by default to the latest released version of CiviCRM. But at the same time have master and older versions available for browsing.  It also supports translations in the way that you would expect, hence URLs would be as follows

/ (redirects to /en/stable)
/en/stable - English documentation for the current version of CiviCRM
/en/4.6 - English documentation for CiviCRM 4.6
/en/latest - English documentation for the yet to be released version of CiviCRM (I suspect the main use case for this would be a preview of the current work in progress manual)
/fr - redirects to /fr/stable
/fr/stable - French documenation for the current version of CiviCRM
/es/stable - Spanish documenation for the current version of CiviCRM
etc.

Development community

The impression I get from looking at both projects is that readthedocs has a bigger development and user community - especially amongst open source software projects. There is a safety in numbers argument here, but perhaps more important is the fact thatt they are focused on functionality that is important for sofware documentation, and we're likely that the project will continue to develop in this direction, providing us with other functionality we can take advantage of.

Developer documentation

Talking to Tim about developer documentation needs, it dawned on me that readthedocs provides a much better platform than gitbook for this purpose. For example developer documentation can be stored in the same respository as the codebase, making it easy to document new functionality as it is developeed.  We can potentially follow the same principle for extensions (though it probably makes sense to keep the user documentation in a seperate respository).  If our developer community is keen to use readthedocs, that would be a good argument to use it for user documentation since we want to keep our toolchain simple.

Positive for both platforms

A couple  other things that both platforms share in common that will be useful for us

• both support webhooks so edits made in repositories can be automatically pushed to the published versions (after review)
• since both platforms are based on markdown it is simple to create PDF and epub versions of the documentation

Making a final decision

Given the above, I'm learning toward readthedocs, but I'm also open to other suggestions and intersted in to hear people's thoughts.  Given that it is reasonably simple to convert from one format to another (and given than git will now provide us with detailed histories of each version of our book) this is not a 'speak now or forever hold your peace' moment, but at the same time it would be good to get the decision right first time if possible since there is bound to unexpected overhead in switching (url rewriting, for example).

Our next big milestone is 4.7 and we're keen to have fully polished documentation published (for both 4.6 and 4.7) when 4.7 stable is relased. We'll be discussing this more in person at the UK sprint and will and make a final decision then. If you have strong opinions on what we should do, and won't be at that sprint (or even if you will!) let us know in the comments below.