Why Read the Docs matters¶

Documenting projects is hard, hosting them shouldn’t be. Read the Docs was created to make hosting documentation simple. I think that we have solved this problem well, but now we need to start thinking about the larger picture.

Along with hosting, Read the Docs was created with 2 other main goals. One was to encourage people to write documentation, by removing the barrier of entry of hosting. The other was to create a central platform for people to find documentation. Having a shared platform for all documentation allows for innovation at the platform level, allowing work to be done once and benefit everyone. Having run the site for over a year now, I think there is a third thing that we should be striving for. That is to make the quality of documentation better.

I think that we can help a documentation culture flourish within the open source world. Django is a shining example of what a project with great documentation can do, and it has a community that values docs more than the norm. I think we can help spread this culture throughout the Python world, and beyond. This has already started, and I want to think about how something like RTD can help.

What we can do to help¶ I think that having a guide for writing useful documentation would be a great step towards helping people along the path of documentation enlightenment. Jacob Kaplan-Moss has started down this road with his blog series and Pycon 2011 talk on this subject. I think that we could start by collecting these into a section of the site. We could build on top of that great start with simple guides for how to get started with Sphinx, best practices for documentation, and providing a general place to learn more about how to write good documentation. Since we host a lot of documentation, we could point to live examples of techniques, and provide helpers for people to enable the techniques. I have started a reStructedText Philosophy document that is meant to help people understand the ideas behind how reST works, so that it isn’t as mystifying. This reST cheatsteet also appears to have similar goals. These are a very basic start, and I think some more along these lines would really help a lot of people get over the barrier to starting and continuing to write good documentation. I think that we could also help create contributors to projects, if we could find an easy way to provide patches to documentation. If you could go to the project documentation, and fix small typos, or help add a paragraph in the tutorial, it would lower the bar to helping. However, it isn’t a wiki. These changes would be represented to the project author as pull requests in their VCS, and they would still be responsible for tending the garden. This gets rid of the “Just Edit The Wiki” solution of documentation, and also helps new contributors get started in an easier fashion. The Plone community has built a proof of concept, linking to Github’s edit pages for the current document. I think we can integrate this at the platform level, and make it available to everyone.