Twitter github

Posts Tagged with “documentation”

September 2, 2010
5 Comments

The Value of Documentation in Open Source

By

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.

March 24, 2010
4 Comments

Singlesourcing and Crowdsourcing Documentation

By

One of the most common complaints I hear about open source projects is around documentation, from the complete lack of documentation to just outdated documentation. There’s many reasons why this is the case, from time to skills but I’m not going to go into that. Yesterday at EclipseCon, David Green and I gave a talk about Crowdsourcing and Singlesourcing Documentation at Eclipse and our thoughts on how to solve the documentation problem for Eclipse.org related projects.

While the talk is focused on Eclipse.org related projects, there is nothing in there that prevents you from taking what we did and apply it to your own projects, whether or not they are open source. The key lessons here is that most developers don’t like contributing to documentation to begin with. They also never have the time. On top of that, if the barriers to contributing documentation is high, no one will contribute and you’ll end up with low quality documentation.

Lower those barriers by enabling a variety of people to contribute documentation, not only people with commit access to the project. If you involve and enable the community to contribute, you may be surprised at what contributions you get.

What other experiences have people faced when it comes to open source related documentation? What can make things better?

March 13, 2010
2 Comments

Crowdsourcing Documentation at Eclipse

By

As David Green mentioned recently, there’s been some momentum building around documentation best-practices at Eclipse. Documentation has always been one of those pain points in Eclipse (or for most open source projects imho), from lack of consistency to not being able to leverage your community to improve the situation.

Through the work of the Eclipse Architecture Council (in particular, Dave Carver) we now have a set of basic documentation guidelines at Eclipse that projects can reference. There’s actually some good stuff in there with pointers to other open source projects on how they handle documentation (e.g., Ubuntu). However, there was one missing piece from those guidelines that always bothered me. For most Eclipse.org projects, the barriers are too high to contribute to the documentation because you generally need access to the source control system and commit access (on top of learning what format the documentation is).

For awhile, a few of us had the thought of leveraging the Eclipsepedia wiki as a source and generate documentation from that. If you use the wiki, all people need is a Bugzilla account and learn simple wiki markup in order to contribute documentation; people don’t need to be committers to contribute documentation! The Mylyn project pioneered this approach with their user guide and FAQ through the usage of WikiText. The only problem with the WikiText approach at the time was that there wasn’t an easy consumable example for people to use and learn from. Thankfully, this won’t be a problem anymore.

At EclipseCon 2010, David Green and I will be giving a talk on Documentation: Single-Sourcing, Crowd-Sourcing And Other Voodoo. As part of preparing for the talk, we created a nice example people can use when exploring WikiText. The example takes the wiki page of the example itself and generates some Eclipse help content from it. You can grab the actual code for the example from GitHub.

We hope the example serves people well and that more Eclipse.org projects start looking to source their documentation from the wiki. If you have any questions, feel free to let us know.

Otherwise, please join us for our talk at EclipseCon if you can.

December 24, 2006
2 Comments

Eclipse Cheatsheet Article

By

Being stuck at an airport provides the perfect time to blog about a new article from the PDE UI team (should we publish this at Eclipse Corner?) that discusses our improved cheatsheet development support. Why use cheatsheets? Cheatsheets provide an easy way to cut down the learning curve for your end users. I think the tools are there now (no more excuses!) for more Eclipse projects to create cheatsheets. So please pressure your local Eclipse project representative to include cheatsheets with their projects 🙂