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
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.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
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
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:
My name is Reinout van Rees and I work a lot with Python (programming language) and Django (website framework). I live in The Netherlands and I'm happily married to Annie van Rees-Kooiman.
Most of my website content is in my weblog. You can keep up to date by subscribing to the automatic feeds (for instance with Google reader):