Lately, I’ve become a big fan of Armin Ronacher’s Flask framework for developing web applications with the Python programming language. One of the reasons I’m a fan is because of its really beautiful documentation. It’s easy on the eyes and easy to use (fit to print, in fact). In contrast to other web frameworks I’ve used, I can’t remember a time when the official documentation or the source code didn’t immediately answer some question I had.

But what’s really astounding about Flask isn’t just the quality of the official docs, but how well that attitude toward documentation has spread to the community. Of some 30 extensions, all have decent-to-excellent documentation. For example, Flask-XML-RPC is practically prototypal documentation for a small, open-source project. It has installation directions, example usage, testing guidelines, and an API reference. These are all areas where some big projects struggle, yet this project manages to get it all right in a single page.

In contrast to Flask’s extension community is Django’s community of reusable apps and tools. Django, like Flask, is a web framework for Python. While Django has prominent documentation that’s comparable to Flask’s, the projects spawned to support Django haven’t quite caught on. For example, South, perhaps the most popular companion project to Django, has a good guide for users, even if it’s not particularly pretty. But while the  South documentation does an excellent job of describing the software and how to use it, the link to the docs is lumped in with nearly a dozen other links on the project’s less than descriptive homepage.

Part of the difference between the Django community’s documentation ethos and Flask’s can be attributed to a difference in scale. Django is immensely more popular; the huge variety of contributors means that a much wider variance of documentation quality is inevitable. But I think the bulk of of the difference can be explained by the steps that Armin Ronacher took to provide an obvious target for related documentation.

Most importantly, Flask’s documentation theme is provided to developers explicitly for use in their Flask-related projects. I suspect that move pushed many extension developers into a fake-it-until-you-make-it position with their documentation. By encouraging third-party documentation to look like the official copy, many of the extensions now have documentation content that is as good as it looks. Along the lines of the argument that school uniforms improve grades, it would appear that better visual design makes for better documentation.

Additionally, the Flask project also sports approved extensions. In effect, they’re just stars of approval on existing extensions. It’s another method used to foster good documentation. Approval requires the project not only to have documentation, but that the documentation use one of the Flask themes, in addition to following several other good practices.

Presently, Flask is the only project I know of to go to such lengths to encourage good documentation from third-party developers, and it appears to be working. Given the results, it looks like a pattern worth repeating.