I’ve been pondering for a while about a way to do open-source style collaboration on documentation in a more effective way. Not a content management system, not a wiki — maybe like a wiki with some structure.

Current score: 0 (to vote for this comment, please visit the site)

Small companies and OSS projects, in my experience, are more focussed on immediate needs and small projects — they need a manual right now for this particular release. Individual contract writers and volunteers are better suited for that rather than consulancies. But with individual work, especially volunteers, you definitely get a big variation in quality in the output. Especially if the company doesn’t really see long-term value in documentation in the first place, or doesn’t see the need to pay up for talent (admittedly the technical communication industry hasn’t been very good at explaining this value in the first place). Maintenance is especially where things tend fall apart. Even if you like to write documentation it really stinks to update it.

Personally I have found some Microsoft developer content to be excellent — the ASP.NET tutorials are the prime example. A lot of the .NET reference content is kind of inscrutable, though, and the navigation is just plain impossible. There have been dozens of times I’ve stumbled on an article on MSDN that explained exactly what I needed to know — and then lost it and never found it again. Drat!

With OSS documentation I’ve found that the popular projects generally have excellent reference documentation (python and PHP, notably). Excellent tutorial and procedural documentation is harder to find. Mostly this is simply a function of the volunteer effort — its easy to write a few reference docs here and there from time to time, and the nature of reference docs is easy to understand and to structure (pick a function, write about it. done). You need a deeer understanding of a project as a whole to write howtos or task oriented docs, as well as more skill in technical writing in general. People who are good at this kind of writing tend to be doing it for money rather than as a volunteer.

O’Reilly (and to a lesser extent the other book publishers) do a good job of filling in the holes in quality tutorial and procedural documentation for OSS. My only quibble with the ORA oevre is that since they focus on the technologists as authors the writing tends to be kind of fair-to-middling. But I’ve learned over the years that an author who is at the same time a good technologist, a good teacher, and a great writer is rare as hen’s teeth.

I seem to have spewed a rant all over your blog. I’m sorry about that.

Current score: 0 (to vote for this comment, please visit the site)

My point is that tiny companies (and open source projects) should be able to do good documentation as well as big companies. It’s just a matter of defining “done” as “thoroughly documented”.

I think that open source documentation can be terrific. A while back I blogged about how much I like python.org — it’s one of the best developer sites around, and that includes commercial and open-source.

Current score: 0 (to vote for this comment, please visit the site)

As Adobe becomes more comfortable in its new role as a developer-focused company (with the Macromedia acquisition, Adobe has a lot more developer tech than they used to), I’m hoping their documentation will improve.

Open Source documentation is never going to be as good as commercial developer documentation. Either it is written by volunteers, or it is written by an organization that makes their money selling support for the product.

Actually, I suspect that some of the larger open-source software companies may have excellent documentation that they simply don’t release to the public, because doing so is not in their financial interest.

The solution to the open-source documentation problem exists, and its name is O’Reilly– but it can sure be frustrating when there isn’t a book on the tech you want to work with.

As a side note– while I agree with you that Microsoft’s tutorials are excellent, your experience of starting with a web search, running into outdated content, and making many wrong turns before finding the tutorial you need is what happens to me pretty much every time I need to find developer content on Microsoft’s site. This is one aspect of the process that I’m amazed Microsoft can’t do better– organizing their documentation, linking outdated documents to the more current versions, and making the whole collection much more searchable.

Current score: 0 (to vote for this comment, please visit the site)