Eric Holscher - Posted in 2014

Announcing Read the Docs for Business

2014-10-24T10:00:00+00:00

I helped create Read the Docs over four years ago. It started with a humble goal of replacing a cron job on my own server. Since then, it has grown more than I ever could have imagined. It has become vital infrastructure for the Python community, and the programming world in general.

Read the Docs has always been a volunteer effort for me. I have gotten small amounts from Gittip over the years, but it doesn’t compare to a developer’s salary It has been a labor of love because I really believe in improving documentation for developers [1].

Companies have the same issues with documentation that open source has. [2] Since Read the Docs is open source, it’s been possible to run it locally at your company. However, running Read the Docs is not trivial. There are a lot of moving pieces, and the code base is always gaining new features.

That’s why today, Read the Docs is adding a hosted solution aimed at companies. It will host your company’s private documentation, and only give people at your company access.

readthedocs.com

This site will live at https://readthedocs.com. The profits from the .com will help fund development on the .org.

We’ve also added some features that only make sense for companies. Since everyone is logged in, you can see who is reading each page. This lets you focus your writing on pages that get read.

https://readthedocs.com is launching today with a private beta. You can sign up for invites now, and we will start letting people in soon.

Why a .com and a .org

readthedocs.org will always be free and available for open source docs.

I love readthedocs.org, and I never want anything to happen to it. readthedocs.com is a separate entity that has been established to bring Read the Docs to business.

This has been a lot of work. Having both live on the same domain would be much easier, but I strongly believe readthedocs.org should never be part of “an incredible journey”. As part of that, we are bootstrapping, and do not plan on taking venture funding. [3]

The fate of readthedocs.org is not tied to the fate of the business.

readthedocs.com has been created to help fund work on the open source project. readthedocs.org should be a resource available to the programming community forever, and I am doing everything in my power to make sure that happens.

Creating a company will help make both the open source and corporate documentation worlds better. Read the Docs solves a real need in the software world, and I hope you join us in the next stage.

Our mission is to build world-class documentation tools for developers, and we would love to have you aboard.

Read the Docs goes full-time

2014-08-08T00:00:00+00:00

We have some exciting news in Read the Docs land this week. The project has been accepted into the Portland Incubator Experiment, as an open source project. This means that we have office space provided to us in Portland for three months, where we will be working on Read the Docs full-time. There will be two of us working on this: Eric Holscher and Anthony Johnson.

Note

Because we now have amazing office space, you can drop by and hack with us any time. We will be in Downtown Portland every weekday. Come work on Read the Docs with us!

This is a fantastic opportunity for the project. Having two engineers working on it for three months will enable us to build a lot of useful things. This week is the first week, and we have already triaged the entire issue tracker and launched a few new features.

New Features

Historically, we haven’t had a great way to announce new features. We would tweet them from the @readthedocs account, and hope people followed us. This isn’t a great format for showing new things.

Today we are announcing a new blog: http://blog.readthedocs.com/ We will be doing regular feature announcements on the blog as we build them. There are a number of recently released features that we’ll be highlighting there. If reading on the web isn’t your thing, you can also choose to get that content via RSS or email:

Adding new features to the project is great in the short term, but something like Read the Docs needs support for the long term. To be able to continue doing Read the Docs, we have decided to spend this time figuring out how to make the project sustainable.

Sustainability

We hope at the end of three months that Read the Docs is a sustainable open source project. We will have more information on this front in the next few weeks, as we figure out what our sustainability model will look like. The goal is that we will be able to create new features and support hosting the project for years to come. If you have thoughts on good ways to do this, feel free to email me.

We really believe in the mission and potential of Read the Docs to improve the state of documentation in software, and we are happy with how far we’ve come. However, this is just the beginning, and we look forward to building the future with you.

How I Judge the Quality of Documentation in 30 Seconds

2014-02-27T22:00:00+00:00

As a developer, you develop instincts for judging quality of code. One of my favorite interview questions is:

When you look at a project’s code for the first time, what are the things you look for?

I think this question is telling. Every person has different priorities, and this is a great way to get at them.

I have developed quick ways to tell the quality of documentation. This post will be about what they are, and what they mean. Obviously it is just a heuristic, and having these things doesn’t make good documentation. However, the absence of them usually indicates a lack of quality.

A Website

If your documentation is a directory full of files on GitHub, I close the tab. With GitHub Pages, Read the Docs, and other places to host generated documentation for free, not making an effort is unforgivable.

If this is your project, please check out Mkdocs. It is still a new tool, but it will give your users something much nicer. I also recommend Sphinx for the most mature approach to documentation.

Prose

If your documentation is generated from source code, I am immediately skeptical. You should use words to communicate with your users, and those words shouldn’t live in your source code. If you included all of the things needed to document a project in source, your code would be unreadable.

So please, use a tool that allows you to write prose documentation outside of your source code. Your users will thank you.

A great start is to read this series on Writing Great Documentation, and the resources on the Write the Docs docs. [1]

Permalinks

One of the primary uses of documentation is the ability to link information to other people. If your documentation doesn’t have an easy way to link to sections of content on a page, then the value decreases. Your users should never have to send someone a link and say “go here and search for X”. That means your documentation has failed your users.

You’ll notice even my blog has permalinks. I believe all text content should, because it greatly increases the utility of the content.

URLs

There are two things I always look for in the URL:

Language

Version

Most often, projects don’t have either. Your URL should look something like: https://docs.project.com/en/1.0/

Versions

I see versions in lots of documentation, but not nearly enough. If your project has versions, your documentation should too. Not everyone can always upgrade to the latest version. If someone is using an old version, they should have access to documentation for that version.

Along the same lines, you should also have documentation for your development version. If the docs don’t have a version attached, I have no idea if they are up to date or not. You should clearly mark your released versions and development version, otherwise users will get confused.

Language

Language is one I rarely see. The software world has a nasty habit of forgetting that the whole world doesn’t speak English. If you don’t provide a language in your URL, you are implicitly sending the message that the documentation will never be translated.

I believe that translating documentation is a really important step towards helping people learn to program. Someone shouldn’t have to learn Programming and English at the same time.

Translations are quite a bit of work, so I understand why many projects don’t have them. But you should at least acknowledge the possibility of translation by putting the language in the URL.

Conclusion

That is the 30 second way that I determine if a project’s documentation is worth looking at. These are all hints about if a project actually cares about its docs. If the project doesn’t care about its documentation, that is a good sign that you probably shouldn’t use it.

Sphinx isn’t just for Python

2014-02-11T16:00:00+00:00

I have heard a few times over the past couple months that Sphinx is “mainly for Python projects”. This line of thinking makes sense, because Sphinx was created to document Python itself. Sphinx however, is a generic documentation tool that is capable of documenting any software project.

The goal of Sphinx is to help you write prose documentation. Prose docs work great for any kind of software you are documenting.

What it doesn’t handle particularly well is generation of docs from source code. This is a task that is best left to a language-specific tooling, so I don’t see this as a major downside of Sphinx.

As I run Read the Docs, I get a chance to see a lot of the different things people are doing with Sphinx. At the beginning, Read the Docs was mostly Python projects. These days though, some of our biggest and most active projects are in a number of languages.

I think that actions speak louder than words, so here is a small sample of projects using Sphinx for things that aren’t documenting Python code.

Creating your own language

Javascript

Bootstrap Datepicker: http://bootstrap-datepicker.readthedocs.org/en/latest/
CasperJS: http://docs.casperjs.org/en/latest/

PHP

Doctrine 2: http://docs.doctrine-project.org/en/latest/
phpMyAdmin: http://docs.phpmyadmin.net/en/latest/
Guzzle: http://docs.guzzlephp.org/en/latest/
Phalcon: http://docs.phalconphp.com/en/latest/
Bernard: http://bernardphp.com/

Java

Inventory Tweaks: http://inventory-tweaks.readthedocs.org/en/latest/
Idiorm: http://idiorm.readthedocs.org/en/latest/

Go

Docker: http://docs.docker.io/en/latest/

Erlang

CouchDB: http://docs.couchdb.org/en/latest/

R

Little books of R: http://little-books-of-r.readthedocs.org/en/latest/

.Net

MassTransit: http://docs.masstransit-project.com/en/latest/
Topshelf: http://docs.topshelf-project.com/en/latest/

Conclusion

I hope that this shows you how Sphinx can be used for documentation all kinds of software, not just Python. It is a fantastically powerful documentation tool, and you shouldn’t discard it without looking at it closely.