Concluding Open Source week in Toronto, Seneca held its annual Free Software and Open Source Symposium (FSOSS) yesterday. I was privileged to have the opportunity to speak about documentation for open source projects.
What is truly exciting about open source development is the collaborative and community aspect of it. I love the synergy of keen minds working on a collective project. Documentation too benefits from having multiple people contribute to and review it. While there is the danger of it sounding a bit like “authorship by committee” I think that problem is easily avoided by having an editor who is responsible for smoothing out the voice.
As we drift more toward topic-based writing that addresses user tasks rather than features, we can accommodate multiple writers because the style guidelines for topic writing are very straightforward. Publishing in an open source environment often involves Wikis, which are an excellent collaboration tool. Marry the idea of topics with a wiki that allows anyone on the team to contribute to the project and you have some excellent documentation that can be developed quickly.
I still encourage documentation plans, and reviews/approvals as part of the process, but generating content is much simpler.
I also still emphasize authorship, meaning document ownership. I don’t mean that someone gets to “own” the documentation in a proprietary way. Open Source is all about moving away from that idea of singular intellectual property toward a collaborative work package that represents the best a group of people can produce. Document ownership is simply taking responsibility for your contribution. Even though other people will look at it and edit it, each author does the best they can to make the documentation excellent.
Another point I brought up in my presentation was that documentation really includes all of the information, communication and knowledge around any particular product. Documentation is a way to add intelligence to the product during development to create a superb user experience. This can be as simple as putting informative labels of data fields that are to be filled in. The example I gave was of a web form that provided for a 10-digit telephone number, without hypens. The user doesn’t know that, however, until they start filling in a phone number 800-555-12 and run out of space. It takes very little effort to indicate how the user should input things like phone numbers, dates, postal codes, and so on.
Of course I recommended that technical communicators be involved in producing the documentation for Open Source projects. I know where you can get some if you want them.
The recorded version of my presentation will be available on the FSOSS web site shortly.
