Salon on why "Linux Needs Help"

Matt Welsh sent us a link to a Salon story on Why Linux Needs Help. It features a lot of truth, and poses the simple question, can free software geeks write software for dumb users? Has a spiffy penguin graphic and a lot of good points (most of which aren't new to us, but they are well written).

Comments

linux, docs, and the future

[dria]

As much as the hackers don't want to admit it, documentation is a very important part of any software product. And documentation is part of the product...it's not something you sort of tack on to the end when you happen to think about it.

I am a technical writer. I work documenting products with GUIs and also CLI products. Here's some stuff I've learned in my two years (yeah, I'm a newbie still) of tech-writer experience:

a) Tech writers do actually have to be technically competent. Those who are technically incompetent might be able to write, but they can't write good docs.

b) Technical documentation cannot be treated as an afterthought. The documentation team should be incorporated into the development process as early as possible...ideally, as soon as the project team is put together. OSS projects can't really do this, of course, because there is no formal process in place...there is no real "team" that is put together for a project...projects just sort of grow and morph and change and develop as time goes on. Or at least that's the impression I get...if I'm wrong, please correct me. I'm sure there are some examples of OSS projects that do have a more formal development process.

c) Technical documentation is a cooperative effort that involves writers, developers, and users. The developers have to provide the basic information and they have to review the documentation for technical accuracy. Writers have to work with the developers on this, as well as diving in and learning everything they possibly can about the product. Users have to provide feedback not just about the product itself, but about the documentation as well. Writers have to use this feedback to improve the documentation and to make suggestions to developers about how usability of a product can be improved. It's all one big symbiotic process that helps create really good and usable products through an evolutionary development process. It takes time and it takes a lot of work and coordination.

d) Technical documentation has to be written for a specific user audience. You can't write good documentation if you don't know who you're writing it for. This means that writers have to develop user profiles, and then write for people who fit these profiles. If you just start writing, you're going to end up with documentation which is way too technical in some areas (you write for experts), way too newbie in other areas (you write for new users), and a mishmash of in-between stuff. This makes for documentation that doesn't suit anyone's needs. This also means that you might have to write more than one set of docs for a particular product: one set for experts, one set for rank newbies, one set for people who are interested in working on development, etc. Defining your users and creating profiles of these users is a key aspect of writing docs (and in developing apps).

er...

Etcetera. I could go on for days about this stuff. My point is this: the OSS movement is sorely lacking in the documentation department. The vast majority of docs that exist are written by the people who developed the applications, which means that most of it is far too technical for the average user. Most of the docs are also written about the particular product rather than about how to use the product. It's extremely important that documentation is task-based and user-based rather than technology based. Writing docs like that isn't nearly as easy as some might think, because as soon as you know how to use a product, you tend to start skipping the details when you write it up.

Oop...I got rambling again. Sorry.

We need docs. We need good docs written by people who know how to write docs. I volunteered to help the documentation effort for one product but I never got any feedback from the coordinator. I'd like to help. I am not a coder, but I do have skills which I think would be useful in context of the larger OSS movement. The problems are: writing doesn't have the same prestige value as hacking code; writing tech docs is not an activity that can be done in communicative isolation (which means we can't just sit in our basements crankin' this stuff out like code hackers do); developers (in general) don't want to be bothered with docs or with helping writers with docs...etc.

Ach. I could go on and on. And on :)

We need good docs. If there are any other tech writers out there who are interested in chatting about this stuff, email me. I could start a linux-writers listserv and we could start hashing out some ideas.

- dria