Off the Beat: Bruce Byfield's Blog

Six years ago, I made my living as a technical writer. I wouldn't want to return to the profession, but, when Esther Schindler recently blogged about the importance of detailed code comments and Carla Schroder about the need for better documentation in free software generally, I noticed.

But, as much as I agree with Schindler and Schroder, I wonder how much of the community is about to give it the attention it deserves. Too much of the community still seems to cling to attitude about documentation inherited from commercial development.

Attitudes to writers (and why they deserve them)

Part of the problem is that technical writers are held in low regard. There is a simple reason for this reputation: Most technical writers know nothing about technology, and the documentation they produce is worthless. The average technical writer is an English major, and is as apt to be attached to the marketing department of a company as to development or quality assurance. In other words, they have little feel for technology, and are encouraged to think of what they produce as a cosmetic extra rather than a necessity.

Of course, technical writers could overcome these handicaps if they wanted. I have an English degree myself, yet I had few problems finding work because I realized early that I needed an expert understanding of what I wrote about.

But this is a minority opinion. The majority of technical writers are under the illusion that all they need are language skills. They see no need to know technology and code. If anything, they look down on this knowledge as less important than grammar and spelling.

With this attitude, the documentation that most technical writers produce may be clear and concise, but it is also superficial and incomplete, and displays no more than a rudimentary knowledge of the software or hardware they are writing about.

So, naturally, developers despise writers and what they produce. In the eight years that I was a technical writer, I got used to having to prove my competence at the start of each new contract. Experience had taught me that other writers had muddied the waters before me.

Just in time documentation

At the same time, commercial developers and project leaders have very little sense of how useful documentation is produced. For a long time, pundits on the subject of technical writing have insisted that writers have to be involved in the development process as early as possible. Yet, in my experience, not one company in six has adopted this practice.

Instead, documentation begins near the end of the development process. Often, it begins ridiculously late -- I have worked on projects in which I was expected to document software with a dozen modules in less than a week, and the best I could do was triage.

Yet, even when the time allotted for documentation is more reasonable, bringing writers in near the end of the project rarely works. Already pushing deadline, the writers are under still more pressure because they have to learn about what they are documenting. Even if they only learn the bare minimum that most writers settle for, their productivity is impaired. To do a proper job and actually understand their subject is next to impossible.

Moreover, at the same time that writers are gearing up, developers -- their main source of information -- are winding down. Often, the developers feel that educating the writers is not their job, or they are ready to relax and disinclined to have writers pick their brains. At times, they go on vacation, leaving writers to struggle on alone.

These same attitudes apply when developers do their own documentation in the form of comments or FAQs. Just like a student writing an essay, who pounds out the bibliography as an afterthought, the average commercial developer writes documentation only after their main work is done, expending minimal thought and less effort, and not thinking how it might be useful to others.

In other words, the prevailing attitude in commercial development is that documentation is of secondary importance. Developers might be fond of advising people to RTFM (Read the Fucking Manual), but everybody still jokes that nobody really reads documentation. The marketing department might want it, but everyone knows that those drones are obsessed with the superficial, right?

Searching for a free software alternative

The division between commercial and free software is not firm. Most free software developers have also worked on commercial software. In fact, these days, free and commercial software can even be the same work. One of the results of this inter-connection is that much of the free software community views documentation as an extra and not a part of their job.

True, many projects, including Drupal, Fedora, and KDE, have struggled to change this attitude. But at times the old commercial attitudes still seem to faintly linger. How often, for example, do you see writers blogging alongside developers on Planet feeds for major projects? At least to some extent, writers and other non-developers still seem to have less status than coders, and to receive less credit as well. Unofficially, writers often seem less part of the community than developers.

This inheritance from the commercial world is not only counter-productive, but needless. Free software technical writers may not be coders any more than their commercial counterparts are, but, given that they are involved in free software, they are unlikely to think they don't need to understand the project they are working on. And, unlike in the commercial world, where technical writing is the last refuge of English majors who can't find a teaching gig, free software technical writers presumably like what they are writing about.

Similarly, despite the move towards twice-yearly releases in many large projects, there is no reason for documentation to be a rushed effort at the last minute. So long as writers can compile source code, they can learn about the software while it is being revised. Nor, in most cases, is there any reason why a release couldn't be delayed until the documentation is ready.

In the same way that the free software has produced superior applications, its projects are positioned to produce superior documentation as well. But, to do so, projects have to shed attitudes that do not apply to their situation. The only question is how many are willing to do so.

Comments