Interesting post by Adrian Sutton, "Stop Using Wikis As Documentation" where Sutton points out some of the problems endemic to using wikis as a substitute for real documentation:
There's a few problems, first and foremost there's no organization. Users don't know where to look for the information they want, it's just scattered around the wiki. Even when an attempt is made at organizing things, it's usually done pretty badly - group the how tos to gether, plonk a link to a getting started guide somewhere and maybe a link to one of the install guides. Rarely do you find documentation that guides the user from getting basic information about what the product does through a simple guide to installing and getting started then on to a feature tour with tutorials etc. In other words, the wiki doesn't guide the user on their learning journey through the product.
Sutton goes on to point out that wikis are fine for howtos, tutorials, and "cookbooks" but lousy for reference guides and getting started guides.
In short, Sutton is saying what I've thought for a long time: Wikis are fine for quick bursts of information that require little organization or cooperation between authors. They are abysmal when you're looking to provide more than a "this is how I got X working on Y this afternoon."
I've said this before, but I do wish someone would do something like the "Google Summer of Code" for documentation -- pick a list of projects that need better documentation and fund student or professional technical writers to actually go through and create or clean up documentation for open source projects to bring it up to professional-level quality. Just slapping up forums and a wiki aren't enough.
2 Comments
I think that although you are completely right in there are many fully undocumented or horribly documented open source applications which are used by thousands and thousands of websites and it is frustrating.
But that's part of the reason for OpenSource being free, they don't give you everything you need, there is no positive business model there. Get pay-for-support and you have a good business model.
As to the direct assault on the Wiki platform for utilization of documentation, quick-setup guides and the like - I think your comments are fairly baseless. Why? Because the documentation efforts of any project is based on the individuals using it. Could you say that there is anything that is hard to use about Wikipedia? Nah. It's so easy it's gonna be on the $100 Notebook projects in participating nations.
It seemingly has been used to add millions of articles and references, images and posts to document much of the living world, and only continues to grow and evolve.
Yes, the non-WYSIWIG interface can be daunting to casual users, including a long-time IT guy like myself, but the overall concept, ability to further extend the application does allow for anything to be 'added.'
Instead of complaining, why not develop some better plugins to achieve the goal you seek with the people who love and utilize the program.
WordPress, and it's Codex documentation - is somewhat too much information and the search results tend to get me lost too - but there is a situation where it's "too much" instead of "not enough." Your dedication to wordpress as a platform for your publishing may be a testament to it in itself.
I'm a complainer myself, but I at least try to lend credible suggestions for solution. Using Google's program to generate documentation isn't a great idea - why? It can only be done by the empassioned users. And there isn't any real groundbreaking application development involved.
"Get pay-for-support and you have a good business model."
Not necessarily. A lot of proprietary apps with support have poor docs, and so do some pay-for-support open source operations.
Wikipedia is a good example of the "quick burst of information," not a well-planned manual. Wikipedia is a collection of articles -- which is what a wiki works well for.
"Instead of complaining, why not develop some better plugins to achieve the goal you seek with the people who love and utilize the program."
Plugins for what, exactly? The problem isn't the lack of a killer documentation application -- it's a lack of people who are good at documentation who are willing to spend their time writing documentation for open source apps, and there are a few reasons for this:
1. The folks who are good at documentation tend to be spending their time doing just that as their full-time gig -- and don't necessarily want to spend an additional 10+ hours a week doing the same thing for open source projects.
2. There's little incentive for tech writers to contribute documentation compared to the incentive programmers have to contribute code. If I'm a programmer, I will probably work on a project that I want to use. Where's the incentive for a tech writer to spend time working on documentation that they'll never read again once it's finished?