Time to Go Home

One of my frustrations as a career technical writer is the need from time to time to defend technical writing as a profession. The argument against technical writing as a profession usually goes along the following lines:

Anybody can write, so why do we need technical writers? Why can't the engineers write the documentation?

My usual response is to explain that the value that a professional technical writer adds to the documentation enhances a corporation's bottom line through:

  • Greater satisfaction for users
  • Lower support costs
  • Lower translation costs

To provide these benefits, the documenation usually has to be clear, consistent, and user-focused. In my experience, clarity, consistency, and user focus are most easily attained by following an agreed set of editorial  guidelines to assure the quality of the documentation. That's why I am such a strong advocate of style guides such as the Sun Editorial Style Guide, from which both Read Me First! A Style Guide for the Computer Industry and the Documentation Style Guide for OpenSolaris are derived.

Earlier today, I was discussing with a fellow technical writer how lowering the barrier to publication might affect documentation projects on which we'll be working in the future. In the course of this discussion, I observed that I am beginning to feel like one of the last examples of a rare and exotic species that is being hunted to extinction. The other writer remarked that I certainly was a dinosaur. When I asked why a dinosaur, the other technical writer replied that it was because of my insistence on grade A documentation when grade C documentation is good enough.

After that conversation, I realized that it might be time to fold up my tent, go home, and find something else to do. If technical writers can't stand up for their own profession, nobody else is going to do it for them.



This is a sad commentary on our industry, but unfortunately, I fewer people see documentation the way you and I do.

Let's set aside the quality issues related to engineer-created documentation for a second. (Surely there are some engineers -- me excluded -- that can write decent documentation.)

Basic economics dictates that documentation created by someone dedicated to technical writing is economically more rational. Specialization is the hallmark of efficient markets. A country, person, whatever is more efficient at producing widget A. Some other entity is better at producing widget B. The most economically advantagous situation is for entity A to make only widget A, entity B to make only widget B and the two entities to trade.

Specialization is efficient. Physicians specialize into narrow fields because it isn't economical for them to be generalists. Likewise, it isn't efficient for engineers to divide their attention between developing software and documenting it. We should encourage people to focus their energy around what they do best.

Posted by Steve Cogorno on October 22, 2007 at 03:49 PM PDT #

Hi Paul. I certainly appreciate how hard it is to write well and the value that technical writers can contribute to the software industry. Here are two thoughts prompted by your writeup...

A novel is very different from a Newspaper article; these two modalities address different needs in the readers, are written within different constraints and exploit different skills in their authors. I think the same variation should exist in technical writing: good writing will continue to be extremely important, it just needs to be adjusted to each of the modalities, from blogs to printed books.

The second thought is on the value of editor. It seems to me that the combination of engineer-contributed content with strong editorial action might be very effective in generating useful and timely documentation.

- eduard/o

Posted by Eduardo Pelegri-Llopart on October 22, 2007 at 11:23 PM PDT #

Steve, I fully agree with your observations about the efficiencies of specialization. One of my most important skills as a technical writer is to be able to view technology through users' eyes while working in the environment where the technology is developed. I have developed this skill only through the continual practice that comes through specializing in technical documentation. I have noticed that even engineers with good writing skills have a tendency to focus more on the internal implementation than on the users' point of view. Given that it's the job of engineers to implement the technology, such a tendency is natural and completely appropriate.

Eduardo, thanks for the endorsement! I agree that different forms of technical writing require different approaches, although some general principles, such as the inverted pyramid style, apply to all factual writing. The partnership between writers and engineers to which you allude in your second thought has always been a feature of the documentation projects that I have worked on. However, for the reasons that I suggested in my response to Steve, some forms of technical writing, notably task-focused information, benefit from a greater level of involvement from the technical writer than subedting content that an engineer has written. The role of writer as subeditor is most suitable for technical descriptions in the form of articles, design specifications, technical papers and, of course, blog postings.

Posted by Paul Davies on October 25, 2007 at 03:49 AM PDT #

I applaud you for making a statement like this. You've raised the Q-word, a word that has seemingly become inappropriate in polite or strategic conversation. The reasons for that are many, but the obvious one related to your topic is that once you invite submissions from engineers, some of whom will be writing in English as a second language, you have to accept a lowering of quality. I could, but won't, offer a number of examples from texts that the editors have worked on. And before anyone thinks we are raising a subjective standard of taste, i.e. sentence A by TW is more elegant than sentence B by ENG-ESL, let me state that we aren't. We are talking about readability and translatability. Poorly written sentences are a barrier to understanding and use of our products, and they are expensive. The obvious expense is in translating costs (25 cents per word x 9-14 languages--and that figure might have risen to 35 cents). The less obvious expense, because good editing is invisible, comes from the increase in editing time required to deal with ESL documents. On the average, IPG editors spend approximately 3 times as much time editing an ESL engineering document as they do editing a document from one of our technical writers. At a time when the editors have about an 18-to-1 writer-to-editor ratio, the addition of texts to be edited from engineers, especially those with ESL, places an extraordinary burden on their time. That is time taken away from style issues, including the new ones emerging along with our new content types (like the text in screencasts), and the involved writer-editor exchanges with our TWs that help produce quality documents.

All that said, I do not share your pessimism, but I do share your concerns. One reason why I don't share your pessimism is because you have the courage to raise this issue and others in your blog. You are not alone in these concerns; there are many other writers in this department who feel the same way. Hopefully your blog provides a forum for their voices in our ongoing departmental discussions.

Posted by Jeff Gardiner on October 26, 2007 at 12:04 AM PDT #

Having just had to essentially rewrite an entire installation guide because the product could not get a writer assigned to them due to the area's VP deciding that his writers should be spending their time on blogs, wikis, and other wonders of the electronic age, this entry really hit home. The guide was written by one of the product's engineers for whom English is not his native language and who had never written documentation before. He also insisted that the document remain in StarOffice so the engineers could "own" the source and update it.

Eduardo, much as it pains me to admit it, a traditional edit is not going to adequately be able to fix a document with poor or no structure and awkward English in nearly every other sentence. For a short article or the like the problem might not be so bad, but for actual product documentation that is intended to be an overall guide to the product and how to use it, there's only so much that an inexperienced engineer can be expected to do. And only so much that an editor can do to fix it without practically starting over from scratch.

Obviously, I agree with Steve, Jeff, and Paul. Programmers would not expect an administrative assistant to be able to write acceptable, useful code, and it's a continuing source of annoyance to me that engineers and management cheerfully assume that programmers can write acceptable, useful documentation as well as technical writers can.

Posted by JaniceG on November 08, 2007 at 11:14 AM PST #

Paul, technical writers perform a valuable function, and I too am dismayed when I come across the 'anyone can write' argument. However, your colleague makes a valid point about grade C documentation being good enough. Documentation is a means to an end, not an end in itself. Documentation exists to make money (or reduce costs) for your company. (It does that through helping customers to use products.)

Quality is the "degree to which a set of inherent characteristics fulfils requirements" (ISO 9000:2005). If grade C is good enough, that is, it fulfils requirements, producing grade A documentation would be wasteful of resources.

The principle of 'good enough' applies to all products and services on the market. Most purchasers cannot afford the best (grade A), even if they desire it. Why should that be different for documentation? The cars we drive, the houses we live in, the clothes we wear. All could be better, but we get by with 'good enough'.

Posted by Mike Unwalla on February 07, 2008 at 04:41 PM PST #

Post a Comment:
Comments are closed for this entry.



« April 2014