Don’t know the words / Kids already hummin’ with it. —Buck 65
Or more accurately, “Is Free, Community-Driven Open Source Documentation Possible?”
A few times a month, I receive an email directing my attention to a new plugin repository or Rails documentation site.
They are usually beautifully designed, but painfully bereft of actual plugins or useful documentation. They are a blank wall, waiting for a kid with a spray can to supply decoration. So far, that hasn’t happened.
People want to help the community, and it seems that the best way is to build a site where people can contribute. The problem is that the people who need the information aren’t able to give it, and the people who have the knowledge are too busy to write it down.
A beautiful looking site is good for attracting visitors, but it isn’t necessarily good for attracting workers. Programmers don’t visit empty sites because they are nice to look at (but graphic designers do!).
What these sites need is content! They need knowledgeable people who are willing to document the finer points of Rails for the benefit of those who are learning it. So mostly, they need a way to attract experienced developers.
In many cases, the founders want to run a job board or Google ads and make a bit of cash from the traffic to their (currently empty) site. Financial motivation is not the problem. (It has worked for me, and people thank me daily for it!) The problem is how it is implemented. It’s a “business plan” that provides no sustaining benefit for those who are actually doing the work (i.e. writing the documentation).
These sites will continue to go up and stay empty unless there is a different kind of “business plan” behind them, one that provides a tangible motivation for people to come and write documentation. Documentation is often boring to write and time-consuming. People don’t do it for fun!
Although there are many aggregators (Planet, Corner) and great news portals (Ruby Inside), no one has tried to organize existing blog articles. What about a system that rates posts and assembles a list of classic blog posts on various topics? (such as Jamis Buck’s classic posts)
Organize it topically, not chronologically. Treat it like a library. Use the information that people are already writing and reward them by sending traffic to their blog.
What if the proprietors could dedicate an hour or two a day toward hunting down and rating top blog posts? There is already great documentation on some topics, but it’s scattered all over the place.
Maybe the Google Ad or job board revenue could even be paid back to blog authors for writing quality posts on requested topics.
If you build it well, I would even consider buying advertising space there each month.
Why have documentation projects failed? Am I right in thinking that continuing documentation is impossible without financial backing or a self-supporting business plan of some sort?