At the end of October, I’ll be giving a talk at Seneca College’s Free Software and Open Source Symposium here in Toronto. That talk will (of course) focus on documentation.
As part of the New Cruelty, I’ve been asking myself a few tough questions while preparing the presentation. One of those questions is Why should the FLOSS community listen to some corporate documentation guy? Admittedly, I’m not all that corporate – I don’t even own a suit. It’s an interesting question, but one which is definitely too narrow.
The question should be What can professional tech writers and the contributors to FLOSS documentation learn from each other? The short answer: quite a bit. The longer answer is below.
Different worlds, similar goals
Let’s start off with what the folks who write FLOSS documentation, who may not be professional technical writers, can learn from our wacky line of work:
- Information architecture – How to effectively develop, order, and arrange information in a piece of documentation or documentation set.
- Topic-based writing – I don’t think that needs any explanation …
- Content reuse – Ways in which to reuse topics or information in topics across a documentation set.
Let’s look at the other side of the coin and see what the technical writing world can learn from the people who contribute to FLOSS documentation:
- Writing as you’d speak – Compare the tone of what you write with the documentation for FLOSS applications. What’s written by professional tech writers can be a bit stiff and business like. FLOSS documentation, on the other hand, tends to be a little more relaxed and informal. The tone is friendlier.
- Working with the crowd – I’ve written about this, and so have others. The nature of our job is changing. We’ll be working with the people who read what we write more. And the FLOSS community has been doing that for a while now. Their experience is something we should tap.
Is that all? Definitely not, and if you can think of anything else feel free to leave a comment.