At the Free and Open Source Software Symposium at Seneca College at York University (not the Markham campus, to my embarrasment), I came in late to the documentation and openness presentation and took some brief notes. Presenter Chris Tyler recommended breaking documentation tasks into beats, which I interpreted to mean have leaders/managers/editors assign documentation tasks, push them just hard enough to write quality and up-to-date documentation, and not assume that "the community" will automatically contribute. (Near the end of the presentation he wondered why many open source projects have, as their suggestion for users' first contribution to the project, writing documentation if they are possibly the least familiar with the product. It might be that I misinterpreted this, but there is some value in encouraging those who are—or, even better, were—frustrated with a portion of the software to voice their frustration at the quality of documentation and submit their own so that others might come in and edit and, if necessary, bring the documentation up to the standards of the project.) He had a favourable opinion of projects like MySQL (or, the example I would have used, PHP.net) as documentation websites allowed for comments where people can comment with their alternate solution or a correction that might later be incorporated into the official text. He also liked the idea of people writing HOWTOs on their own weblogs. He complained about the unidirectional nature of links in the current version of the Web (2.0 if you didn't already know), but documentation with comments open would permit dropping a link in the official documentation's page, making it a "manual trackback" of sorts.

In the discussion, someone mentioned that there's a balance between professional quality and community input. As well, someone mentioned the desire for a balance between community involvement and appropriate length of documentation (especially true of wiki pages, but also applies to documentation with comments enabled), as individual pages may become unwieldy over time. Video documentation (the word screencast wasn't mentioned, but many software packages defy easy written description but can be shown in a few minutes or even seconds). The other problem Chris mentioned about documentation —other than asking users to contribute help texts when they may not be familiar with the product, addressed above—was translation of documentation and keeping the translations synced up, especially with documentation in wiki format. A few times the people in the room mentioned the need for new tools but a lot of the problems sound like they can be solved better socially or organizationally.

Naturally metadata made its way into the discussion, and more than 2 people were frustrated with the way the Google search engine is setup for people to find documentation. I don't share their frustration, nor do I share the frustration with the seeming lack of authority of documentation found on sites other than the project's official website, because for the vast majority of problems I needed solved I've found through a basic search engine. Granted that much documentation needs to be 'tagged' for the version that it describes, but the tools for doing that exist: it's a matter of "just" doing it.

Some things not addressed by the presentation, at least not while I was there was documentation hosted services based on open source software? While I'll be the first one to admit that <ahref="http://support.bryght.com/">Bryght's support documentation is not always complete (that's what the support forums are for, so that people can ask questions and then we can update the documentation with our answer) nor is it always up to date (mea culpa), Bryght has a larger degree of control over what version of the software running there than a downloadable product, since Bryght does all the updates for everybody. I'd also be interested in how companies contribute their documentation back to the communities from which they run their hosted services (or even from where they get the software they host a possibly modified version of for download). People are free to use Bryght's documentation for their purposes since it's licensed under the Creative Commons, though there's no automated way other than screen scraping or copy & pasting to migrate documentation from one place (support.bryght.com) to another.

Next up, in a few minutes, is Eric Shepherd's presentation on documentation in the open source world. From the looks of the summary, it looks to be about developer documentation, not end-user documentation, which I think is more interesting if we're to help sell people on open source.