A few days ago I got one of the best assignments I could think of at work - to check the web out for interesting Django packages and find out if any of them could be of use to us. It’s… pretty awesome.

So, in the last few days I’ve been reading a lot of package documentation. My goal was to get a list of popular and recommended Django packages, briefly review each one to get a feel of what it does and decide which ones are worth taking a deeper look into. The “briefly” part is where my expectations met a surprising reality.

What I found is that most (if not all) Django package developers are pretty responsible and provide a pretty comprehensive documentation. Thumbs up for that! Unfortunately, they are mostly comprehensive, which is great if you’re using the package and are looking for help with something, but not so great if you want to just get quick information on what it does.

Case Study

Let’s look at an example. There’s a Django package called reversion¹ Here’s the introduction from its README file:

Django Reversion

django-reversion is an extension to the Django web framework that provides comprehensive version control facilities.

Features

• Roll back to any point in a model’s history - an unlimited undo facility!
• Recover deleted models - never lose data again!
• Admin integration for maximum usability.
• Group related changes into revisions that can be rolled back in a single transaction.
• Automatically save a new version whenever your model changes using Django’s flexible signalling framework.
• Automate your revision management with easy-to-use middleware.

This looks nice - except that I couldn’t for the life of me understand what “version control” for models is. I understand that it’s probably either keeping track of data changes in your database over time (a sort of database backup, so you could revert it to two weeks ago, before that damn bug occured) or keeping track of Django model changes, i.e., model schamas, like south does. There is nothing in this introduction to give me a hint, so let’s look a bit further. There’s a “Getting Started” section in the docs, and that’s always helpful, so we’ll check it out for quick examples, right?

Getting started with django-reversion

To install django-reversion, follow these steps:

[..]

Admin integration

django-reversion can be used to add a powerful rollback and recovery facility to your admin site. To enable this, simply register your models with a subclass of reversion.VersionAdmin:

import reversion

class YourModelAdmin(reversion.VersionAdmin):

    pass

admin.site.register(YourModel, YourModelAdmin)

Whenever you register a model with the VersionAdmin class, be sure to run the ./manage.py createinitialrevisions command to populate the version database with an initial set of model data. Depending on the number of rows in your database, this command could take a while to execute.

For more information about admin integration, please read the admin integration documentation.

Low Level API

You can use django-reversion’s API to build powerful version-controlled views. For more information, please read the low level API documentation.

More information

[..]

There’s a code snippet here, which is excellent. Examples are great when you want to know how using a certain package looks like. I could further infer that reversion probably referes to model data and not schema from that bit about the rows in the database - but it’s purely coincidental.

But that “Admin Integration” bit is a bit weird. It seems reasonable that reverting to an earlier version of a certain model would be done in the Admin page, but from this paragraph it’s not clear how this would look like and how usable it is. Or to put it another way - pics or it didn’t happen. Why can’t I get a nice screenshot here? A solid screenshot of how the admin page looks like would probably inform me more about what reversion does than the many pages in this documentation.

All in all, it took me about 20 minutes of looking around the documentation to get a feel of what it does. This includes searching google for “django reversion screenshot” so I can see how it looks (partial luck with that search, by the way). This is way too long.

Be Better

A package documentation should server (at least) two purposes:

1. It should act as a “pitch” - allowing new users to quickly assess the purpose, usage and benefits of the package.
2. It should act as a reference for users already using it, in case they have questions or issues with the package.

Most packages focus on the second point, but it’s only useful if you get people to use your software, and you get it with the pitch. So how do you do it?

Pitch Recipe

1. There should be a specific section of your documentation dedicated to the pitch. It should be named clearly as such - “Getting Started”, “Quick Start”, “Tutorial” are all good, indicative names.

2. That section should either be in the landing page for your docs or clearly linked from it (think bold letters).

3. The pitch should clearly state what the software does. Ideally, it should also state what problems it solves. Think about drug commercials. Start with symptoms, then the solution.

4. If there are different packages that do the same as yours - this is the place to let the user know what makes your package different.

5. If your package has ANY graphical interface you HAVE to include a screenshot. You wouldn’t buy a painting just from a description, would you?

6. You should include a minimum working example of your package. The example should be simple, yet meaningful. If you’re declaring a class called Foo, you’re doing it wrong. The example doesn’t only answer the question of HOW to use your software, it should also answer WHY.

You make great software - help people use it!

Similar Posts

• Python Attribute Access and the Descriptor Protocol
• File Parts: Cheat Sheet
• Python Idioms: Multiline Strings
• Python Entry Points Explained
• Cleaning Up in a Python Generator Can Be Dangerous
• Write Explicit Tests