Just a Gwai Lo - fun within prescribed limits

In a week, I will attend the Writing Open Source conference in Owen Sound, Ontario. I'm excited to meet some of my colleagues in the field of open source documentation, having written the bulk of the support materials for Bryght, the Drupal-powered hosted service. I'm particularly interested in meeting those working to document open source tools other than Drupal, to gain some perspective on what's out there and what's needed.

Writing documentation was my first task at Bryght back in 2004. I recall spending part of that Christmas break furiously jotting down the important steps to creating dynamic and community websites. This included checklists, instructions and descriptions of module settings and how people could take advantage of them. The initial push of documentation made the subsequent job of supporting customers easy: instead of each time having to explain how to do something, I quickly pointed to the documentation, either through a link or a copy & paste. Along the way I even heard from non-customers thanking me for the handy references. After the second time someone asked we documented the answer. (We even wrote documentation after the first time someone asked a question.) Sometimes it didn't work, and sometimes the documentation wasn't all that great or hard to find. We allowed comments and opened the forums and listened to feedback when what we wrote didn't make a whole lot of sense. That's the experience I'd like to share with the conference, and I'd like to hear of others' experiences in making complex software more understandable.

After the weekend conference, I'll spend a couple of full days in Toronto proper, getting some much needed distance from Vancouver. I'd like to meet with some of the Toronto Drupal heads, and others I know (but haven't met) from other online communities I'm part of. Sadly, my favourite baseball squadron, the Toronto Blue Jays, play on the road in late June. Surely a local pub will have the games in HD? read more →

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 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.