Great Documentation Is Key to Open Source Success
Listen up open source developers, if you want your project to succeed you’re going to have to do more than write great code; you’re going to have to document it, teach new users how it works and provide real-world examples of what you can do with it.
That’s the message from Jacob Kaplan-Moss, one of the creators of Django, a very successful open source, Python-based web framework. At least some Django’s success can be attributed to its thorough documentation which is not just reference materials, but also includes tutorials, topical guides and even snippets of design philosophy.
Of course Django is not alone in having great documentation; Ruby on Rails is another highly successful open source project featuring great docs, tutorials and reference materials. Beginning to see a pattern? Great docs == happy, enthusiastic users == open source success.
Too often open source projects seem to turn up their nose at documentation, arguing that the code is well-commented or that developers should be able to figure it out for themselves — with the implicit suggestion that those who can’t don’t matter. That’s fine for some projects, but if you want your code to be more than a random page on Github, you’re going to need good documentation.
In an effort to help other projects improve their documentation, Kaplan-Moss has embarked on a series of articles outlining what he and the rest of Django’s developers have learned from the countless hours spent creating and refining Django’s docs.
While it’s worth reading through the entire series (and there’s more on the way), the basic message is quite simple: good documentation is more than just technical reference material.
What makes Django’s documentation stand out (and Ruby on Rails as well) is that it covers the details as well as the high-level overview of how the details fit together. Kaplan-Moss breaks down the types of documentation into three basic categories:
- Tutorials — Tutorials are a great way to introduce users to your software and demonstrate high-level concepts in real world examples. Too many tutorials teach you little more than how to create a “hello world” script. Good tutorials should help your users actually build something, which is much more exciting for a new user than printing out a line or two of text. As Kaplan-Moss says “that rush of success as you work through a good tutorial will likely color your future opinions about the project.” Tutorials are the best way to make a great first impression on your potential converts.
- Topical Guides — This is the real meat of good documentation and will be what users return to over and over again as they learn how to use your software. Kaplan-Moss’ advice is to aim for comprehensiveness: “the reader ought to come away from a close read feeling very comfortable with the topic in question… they should feel that they know the vast majority of the possible options, and more importantly they should understand how all the concepts fit together.”
- Reference — Sadly reference materials are in fact what passes for documentation in much of the open source world. That’s not to demean reference guides; complete lists of class names and methods are absolutely necessary, but don’t stop there. As Kaplan-Moss writes, “think of guides and reference as partners: guides give you the ‘why,’ and reference gives you the ‘how.’”
If you’d like to see an example of well-done documentation that covers all these ideas, look no further than the Django Project website, which hosts all of Django’s documentation. The Ruby on Rails community has also produced excellent documentation.
Kaplan-Moss has two more parts to his documentation series, one in which he delves into topics like writing well, developing a clear, grammatically correct style and another that focuses on editing.
Kaplan-Moss’ post on technical style also covers things like markup and structural layout of documentation, since even the best documentation is useless if you can’t find what you need. For example one of the best parts of Django’s documentation is that every topic and reference page has a liberal dose of inline links that make it easy to jump from one section to another. While we wouldn’t suggest using wiki software, the everything-is-a-link model of wikis makes a good starting point for marking up your online documentation.
One of the biggest hurdles for many open source projects is finding good writers to create documentation. While Kaplan-Moss has some suggestions for making yourself a better writer, many developers don’t have the time to improve their writing skills. To that end we suggest paying close attention to your community.
Watch for blog posts from your users that offer tutorials or provide an in-depth at some aspect of your software. Contact the authors and see if you can incorporate their posts into the documentation. Give your users a chance to contribute not just code, but their understanding of the code — ask them to write more and make them a part of the project when appropriate.
Finally, perhaps the most important message of Kaplan-Moss’ post is that ultimately… some documentation always trumps no documentation.” Maybe your documentation isn’t on par with Django or Ruby on Rails, but don’t let that stop you from producing at least something. And be sure to check back with Kaplan-Moss’ site for more articles on creating good docs for your project.
See Also:
- Django Project Looks Toward the Future With Django 1.2
- Making Open Source Software More “Humane”
- Flush With Choices, Developers Still Dig Django the Most
Google has released a brand-new programming language it hopes will solve some of the problems with existing languages such as Java and C++.
Now, you can do the same crazy user interface stuff Google does on sites like Gmail and Google Docs on your own website.
Developer Mark Pilgrim has posted a fascinating look at how the HTML 
The developers behind the 
Yahoo has announced the official release of version 3 of its open-source Yahoo User Interface (YUI) library. The new framework is designed to simplify the process of building complex web interfaces.
Tr.im, the popular URL-shortening service for Twitter and other social networks has 
