Writing a README¶

Tags: python, django, nelenschuurmans

Good documentation is important. I just heard two colleagues talking and what one of them said sounded like a README:

- Install the shit.
- Run it.
- Look for error messages.

It triggered me to write a blog post as I was just busy writing a README for a small script. pip install is currently compiling numpy and matplotlib, so time enough for me to gather my thoughts.

“Good documentation is important”, yes. But there are many things that we can all agree on “yeah, that’s important, too”. “Being important” isn’t the same as “actually getting written”. Many of the small tools and django apps that we write aren’t actually going to see widespread use. Many are company-internal, effectively. Is read-the-docs level documentation useful/necessary?

In some cases, yes. One of the company-internal django apps I wrote has extensive documentation and 100% test coverage. That’s what you get with something named “lizard-security” which uses django’s row-level security and some special settings and other tricks. Especially when it is used in almost all our sites.

In most cases, nobody is going to bother looking up the official documentation, even if you wrote it. All they’ll glance at is the README. And in most cases, that’s fine.

Github helps a lot here. If you’ve got a README.rst, README.md, README.txt (etc.) at the top level of your project, it’ll be rendered prominently. This makes it easy to spot. For small tools or not-often-used apps I normally look at the github page anyway to see if it was recently modified and who’s been working on it. The README is right there in your face.

To me, there are a few things that absolutely need to be in a README:

• Installation instructions. If it is just a normal django app installed in the same way as all the others, don’t bother. But do tell me if I normally need to do something special to my django settings, like adding middleware or configuring some value.

• Manual tasks. The normal setup.py/pip/buildout/make automation stuff should handle most of it, but sometimes there’s something extra. “Mount some network share into var/shapefiles/.” “Copy the *.csv you got by email from the client into var/csv/ and run bin/django calculate_all”.

• Getting-started instructions for non-standard projects. Everyone on the team knows what to do with an unknown django app. A bit of looking at urls.py, views.py and models.py and you’ve got a pretty good idea of what it does. And you can get up to speed pretty quickly.

  But what about one-off scripts? Where “one-off” means “you’re pretty sure someone is going to need it in two years’ time”? Or something essential that runs in a cronjob, faultlessly, but that’s going to break in some weird way when you’re on holiday and someone else needs to take a look?

  They’ll love you and you yourself will love you if there’s a quick reminder in the README on how it all hangs together. “Mount this directory.” “For a quick test, run bin/weird_thingy sample_data/input.csv and it should do xyz.” “It is installed on server A, but server B is the one that has the apache rewriterule that we depend on”.

Let me finish with two documentation-related quotes that are simply stuck in my head and that pop up every time I think about documentation:

• Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live. (link)

• Document the shit out of it, like it was for your grandma. (Chris McDonough, link).