In the Doc Dish column, we often have focused on writing documentation, but that's not the whole story. For what shall it profit a writer if they write the whole document and have no readers? Once documentation is written, it must get in front of the user so to be read. For anything beyond simple readme files, this can be a challenge; often documentation writers need design, hosting infrastructure, search tools, and so on. One project aims to make that a little easier.
Read the Docs is an open source (MIT-licensed) project that started during the 2010 Django Dash. The goal of the project is to improve the quantity and quality of documentation by reducing barriers. Although Read the Docs can't write your documentation for you, it does handle automatically building from your source code management system. Docs are rendered as HTML and PDF and full-text search is included.
Thousands of open source projects host their documentation on the Read the Docs site, and others use the Read the Docs code to self-host. Additionally, the team has started a paid service for commercial and private use.
Read the Docs solves so many problems, why wouldn't you use it? The main reason would be if you're writing your documentation in something other than reStructured Text. Read the Docs uses Sphinx for rendering, so until Sphinx supports other markup languages, your options are limited. All hope is not lost: The Read the Docs team added CommonMark support to Sphinx, so you can add whatever language you need, if you're so inclined.
Of course, there are other ways to contribute to Read the Docs. The most pressing need is for additional people on the Support and Operations teams. Support team members help users diagnose and resolve problems via GitHub issues. The Operations team takes turns being on call to keep the site running 24/7. More information about those contributions is available on the Team page. Financial support is also possible by recurring Gold subscriptions or one-time donations to the sustainability campaign.
With Read the Docs, there are no more excuses for not getting your documentation published in a place where users can find it.
Do you have a Read the Docs experience to share? Let us know in the comments, or submit a Doc Dish article proposal.
1 Comment