Let’s write some docs

Dave Dash

3

We decided to sponsor Read the Docs in a roundabout fashion.

Documentation is important. It helps us understand what it is we’re building, and since everything we do is open source it helps others understand how to use our tools or contribute to us.

Before the Great Python Revolution at Mozilla, we were documenting things in a wiki, and relying on good habits to keep documentation up to date. Good habits are hard to maintain.

Once we started using python extensively, writing things in Sphinx seemed natural. Since a lot of our projects were in GitHub, we wrote a lot of scripts to automatically build our docs and push them into Github Pages. This also suffered from hard to maintain good habits.

We eventually stumbled upon Read The Docs. An open source project that automatically takes your documentation and builds it and hosts it. Slowly we started pushing more and more of our projects to Read the Docs. Suddenly writing documentation started to pay off. Our results were immediately visible, and documentation now became a priority.

So we decided to support Read the Docs by giving them a build server. The architecture at Read the Docs makes it so that they aren’t dependent on our server, but since it’s there it will get use, and it will make building documentation a lot faster and easier. Our hope is that more open source projects will put time and effort into documentation, thus making them easier to use.

So have a look at this amazing project and start writing some docs.

3 responses

  1. Fred Wenzel wrote on ::

    Thumbs up! Read the Docs is a great tool. The easier it is, the more lazy developers like you and I are inclined to write docs :)

  2. Aakash Desai wrote on ::

    Huzzah! Documentation should be a priority for all open-source projects and I’m incredibly excited to see us leading the cause here! Great stuff.

  3. Nigel wrote on ::

    Love rtfd! Great that you guys are supporting them :)