Experiments with read the docs

2015-10-03 14:18
Written by

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

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.

Filed under
Click thumbs up if you thought this blog post was useful (login to vote or to comment)


Thanks for the work you've put in on this, and for writing it up. I've had very little exposure to either of these two approaches, so can't really comment on any of the details you've set out here. I will instead offer just one suggestion that I think should be taken into consideration during the decision-making process:

Given the fundamentally important push to grow the community of actively engaged users, I believe that enabling users to contribute towards the documentation effort is a really important way to engage ordinary CiviCRM users and bring them in to that community. Consequent to that it is critical that it should be extremely easy for those ordinary users to make such a contribution. This means providing an editing interface which is simple, clear and obvious. They should not need to deal with jargon, or install software, or anything like that. https://github.com/civicrm/civicrm-user-guide doesn't currently meet that brief. As you say things are moving fast in that space, so better tools will hopefully become available. In the iterim, we need to factor in creating some guidance for documenters that does all it can to smooth out the bumps and makes it easy for users to get involved.

This might be an answer to giving a user-friendly editing interface for end-users:

Prose is a web-based markdown editor for Github Pages. http://prose.io/#about

I have not looked at this in details, but it seems like it can connect to a github repo and provide a markdown editing interface for pages stored in the repo.

Anonymous (not verified)
2015-12-21 - 07:00

Thanks, Michael, for all your work on this. Could you give us a status update please? My new client needs links to documentation in advance of development but the CiviCRM Documentation wiki still directs to the User Manual for 4.5 at the broken Booki/Flossmanuals site whereas search engines also find the much better gitbook site that presumably documents 4.6 but doesn't say so. Now there is the experimental ReadTheDocs site that you're hinting might be chosen. CiviCRM is complex enough without rival manuals.

What do we need to resolve this? Can we at least nobble links to book.civicrm.org for 'current' and above and put something into it to direct most people to gitbook for now?


http://book.civicrm.org/ is the authoratative link for documentation, which points to http://gitbook.civicrm.org/ for the 4.6 documentation.

Can you share a link to the wiki page that is referencing the flossmanuals site, so we can update the out of date links (or even better, you could update them for us).


Update: Michael has confirmed that readthedocs rather than gitbook or prose is the current official platform for documentation (https://issues.civicrm.org/jira/browse/CRM-17688).

Quick FYI for people that are working on user documentation at the moment.  The old gitbooks based https://github.com/civicrm/civicrm-user-guide repository has been deleted (well, transferred to renamed here: https://github.com/michaelmcandrew/civicrm-user-guide-gitbook.  The read the docs repository that was called https://github.com/civicrm/civicrm-user-guide-rtfd has now been renamed to https://github.com/civicrm/civicrm-user-guide.