Twitter github

The Value of Documentation in Open Source

I’ve been starting a lot of documentation work lately for the EGit/JGit projects and happened to come across this timely article from Forbes. If you don’t want to read it, the gist of it is that solid documentation is more important than you think… especially when it comes to attracting a user and developer base. Here are some quotes…

“I can report that my company receives 70% plus of our site traffic from organic sources, and our documentation generates more than half of our overall site traffic. Furthermore, over half of our lead generation is driven by our documentation.”

While the article specifically mentions commercial software, I think the lesson of having solid and findable documentation apply to the open source realm. I mean, when’s the last time you’ve come across an open source project that you praised their documentation efforts? I can maybe count two total in my lifetime. As open source developers and project leads, we tend to put documentation last and our expectation is that users would pitch in to help. As users, we just want good documentation and don’t believe it’s our responsibility to help out necessarily…

So next time you’re working on that feature, weigh it versus taking some time to document things for your users. If you’re in Eclipse land, feel free to take a look at our documentation guidelines and some examples on how to crowdsource your documentation efforts a bit.

  • Tim O’Brien

    Crowdsourcing documentation has never yielded great results for anything other that the largest open source product. You approach the documentation effort in the same way you approach the core of an open source project, you have to fund development of good documentation.

    I had a similar experience as the author of this Forbes article (coincidentally I did an interview with another Forbes author on the same topic last year). Good books drive traffic numbers.

  • The only problem with books is that they are a significantly larger investment in time than say some solid documentation on a wiki. Especially if the people writing the books are the folks writing the project code. This may be common in a lot of small to medium size open source projects. The larger projects tend to have more commercial interests and there may be people willing to write books outside the immediate project team.

  • The only problem with books is that they are a significantly larger investment in time than say some solid documentation on a wiki. Especially if the people writing the books are the folks writing the project code. This may be common in a lot of small to medium size open source projects. The larger projects tend to have more commercial interests and there may be people willing to write books outside the immediate project team.

  • Robin Rosenberg

    Seems I’m not the only one that never ever look at the directory of documentation or press F1 for help, when googling is usually many times faster and better. šŸ™‚ If the documentation is any good it is probably what Google finds anyway.

    I think the emphasis is on solid so that when people find it, the are helped by what they find. Only the public the mailing lists probably confuses since a lot of threads are open ended, while wikis and bug trackers are more complete.

    Being findable is perhaps obvious for OSS, since everything is on the net, there for the crawlers to seek out. Then it’s a matter of what they find. We might want to be more careful about how we write our wiki pages and javadocs.

  • It’s a great advantage to any open source project to have a committed and savvy technical writer on the team, but in my experience that only happens when there is some funding available. Wikis are easy to change, which is helpful, and documentation guidelines are useful, but IMHO the biggest challenge is that of staleness – consistently keeping the documentation correct as development changes minor behaviours is a big challenge in a typical ad-hoc development environment. Stale documentation is wrong – which in some cases is worse than documentation that doesn’t exist at all. Google and the indiscriminate nature of the internet doesn’t help here: documentation that is out of date or incorrect doesn’t evaporate, it stays in place to misinform and exasperate future generations. Projects should always consider versioning guidelines for their documentation that are just as stringent as those they use for the software.