Documentation: Give it up; it won't happen.

At one point in time and not too very long ago, I fancied myself a decent system administrator with a decent resume and work history. When I finished a series of writing tasks working on technology subjects that included system administration, I thought the time had come for me to work in a shop with Linux and MS.

I put my resume up on Dice and Monster and waited for the phone to ring. When it didn't ring, I went up to see the hits. I saw six on Monster and eight on Dice. Only one company saved my data.

I don't know what possessed me to build a tech writer resume, but I did. I had enough experience and I wrote the white papers no one "got around to", user manuals, policy and procedure guides, S-1 SEC registration sections and so forth. On Monster I immediately started getting hits - something like 164 in a week. On Dice the number was something like 186. I switched back to my sysadmin resume and again I got four to eight hits. That's counter intuitive to my experience.

As a friend at JBoss once said, "gotta eat". So, I started accepting short-term writing assignments. I learned several things about the field. Aside from the massive requirements of documentation for such things like Sarbanes Oxley, HIPPA, SAS70 and warehousing of data, many companies had a trick up the sleeves. They advertised for a technical writer, but they really wanted business and system analysts they could land for $30-35 an hour.

I have yet to see a position come my way that wanted an internal writer who checked for grammar, spelling and business rules. The prospective employer wanted someone with UML, EDM, Visio and MS Project experience. They also wanted someone to back an undocumented software application into its original specs. The job requirements: Re-engineer a running application that never had functional of technical specs.

I took two projects like that at some very large companies and discovered a massive chasm in documentation and if any existed at all - a lack of updates. That led me to think about my experiences attempting to fix and document some popular Open Source projects. If large corporations with plenty of resources have neglected their docs, then what can we expect from a community whose contributing members are almost entirely programmers.

Open Source documentation has a lot in common with the corporate world. On my last assignment, I discovered a large population of wikis. Every department had at least one. At one point someone maintained those information storehouses, but almost all of them sat on the Intranet barren and abandoned. I asked people if they knew anything about their department's wiki and I found one person who even knew one existed. She maintained it daily.

Is providing Linux documentation an insurmountable task? I'm starting to think so. The major technical book publishers have dropped their efforts to recruit authors and publish sysadmin books. Instead, they have started focusing most of their attention on programming. Who can blame them. To eat, they had to publish books that sell enough to pay for the effort and provide some return on investment. That's not happening right now.

I'm not discouraged or suggesting you or anyone else stop posting information for others to find. I just see the job as bigger than me and almost any other writer. The heyday for technical writing specialists has arrived and a shortage exists. I'm just glad I took Miss Johnston's English class., where I got lots of detentions so I could stay after school and hang out with the teacher.


Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Grammer & speling

Howard's picture

"Re-engineer a running application that never had functional of technical specs."

Did you mean, "Re-engineer a running application that never had functional oR technical specs." I was looking for information about you, and was very much surprised to find dozens of postings from you with spelling and grammatical errors. Some were bad enough that even after 3 or 4 attempts to parse them, I still couldn't puzzle out what you were trying to say. If you still have access to those blogs, you might want to go back and clean them up a bit.

"They advertised for a technical writer, but they really wanted business and system analysts they could land for $30-35 an hour."

And you are surprised? The ridiculous pay has pretty much kept me out of technical writing. Now that I'm getting too old, er, "overqualified", to write software for a living, I'm getting ready to expand my other businesses (I expect a pink slip as soon as they land the Delphi 6 contractor for which they are frantically searching). When you need your CHL renewed, look me up ( BTW, I sent you an email to a yahoo address which was the only one I could find for you. If this comment should come to your attention, please contact me.

And best of luck with the watch repair business.

sounds good...only if the

Anonymous's picture

sounds good...only if the teachers cute, though :)

One thing that would help is

Anonymous's picture

One thing that would help is to keep up the encouragement of companies who use open source in their businesses to contribute financially.

It's not just about new code.

Make them think about putting back a percentage of what they would have spent on a proprietary software in the given year. This money could well be used to write better documentation.

Another reason we need professional tech writers

Scott Abel's picture

Technical communication for far too long has been viewed as a necessary evil. In organizations that value their content as a business asset, documentation is part of the product, not an afterthought.

Modern documentation methods, such as the Unified Content Strategy (See "Managing Enterprise Content", by Ann Rockley, New Riders Publishing) and the Darwin Information Typing Architecture (an OASIS XML standard for creating topic-based content) are two of many approaches that help organizations create professional documentation in a manufacturing style approach. Documentation pros with an understanding of software development practices (there are many of us) are highly sought after (and well paid) information architects and document engineers (see "Document Engineering: Analyzing and Designing Documents for Business Informatics and Web Services," by Bob Glushko, MIT Press). That's because documenting software is not about English, semi-colon usage, wikis, or code. It's about the user and the intent of the communication -- and it's about not wasting money.

Additionally, professional technical communicators also utilize controlled vocabularies and authoring tools that can help them prevent ambiguous language from slipping in. This minimizes usability problems in the native language in which the content was created and makes translating the content less expensive and error-prone.

Our single-sourcing approach, married with XML component content management systems, allows us to write content once and automatically reuse it where needed.

Documentation professionals don't just write (although, admittedly, some technical writers still think that's their job). They are actually part of product development and often contribute to the user experience and interaction design processes. In organizations that understand the value of paying for content to be written by a knowledge worker (tech writer, developer, or whomever) metrics are being used to make the business case for getting rid of old school "We'll just jot some stuff down" approaches. And, interestingly, developers who also have a mastery of their native languages, are also entering the arena.

It's an interesting time to be a technical communicator. If the posts from developers are any clue, we'll be needed for a long time to come.

My two cents,

Scott Abel

I'd like to reprint your post on my site

Scott Abel's picture

I'm interested in reprinting your post "Documentation: Give it up; it won't happen" on my blog, The Content Wrangler. My audience of 17,000 subscribers (and thousands of others who stumble across the site on the net) would be very interested in your views. And, I think it might start some discussion.

Your thoughts?

Let me know.

Scott Abel
The Content Wrangler

It starts in development

Anonymous's picture

I have been a developer for proprietary and FOSS apps. Ultimately the doc buck stops at the developer. Most tech writers cannot dive into the code to figure out how it works, even if they had the time.

I have never bought into the idea of writing a complete functional description before starting to code--except for the most trivial programs/libraries, it is going to change over time. So I have tried to figure out the most productive way for me to produce doc as part of my development work. It's definitely not perfect, but here is what I am doing at this point:

1) Write a very high level description of the app. This is no more than 3 pages, and only includes the basic functionality and primary features. Keep this around and update it occasionally so you have something to give anyone who asks.

2) Write a somewhat high level system description. Each major component becomes a source file, and the description of that component is formatted for doxygen ( and placed at the beginning of the file.

3) Write a reasonably detailed description for each function, formatted for doxygen. This is done before any code is written, and updated when the function is completed. I also try to keep my functions in a logical order so that it is possible to get a sense of the program flow.

4) For every error message issued, there is a comment that includes the message, a description, and the administrator action. These are written to a messages file. I was able to use doxygen for this up to 1.3.6. However recent versions do not allow comments within functions to be written to a separate document/web page, so I am planning to write an awk script to generate my messages manuals.

I have been working on my FOSS project for over 4 years, and this doc has helped me get back up to speed on code that I may not have looked at in several months. I also found it useful when writing man pages.

That does a pretty good job of handling developer doc. The next step (and it is a big one) is user doc. Unfortunately, I haven't figured out how to do this other just writing it. And it's hard to shed all of the underlying assumptions that I have from working on it so long. If anyone has any hints on this, I'd be interested.

Later . . . Jim

RenaissanceCore IDS, check it out at:

I agree.. documentation is more of an afterthought.

Ben's picture

Even in the system administration work. First you get the thing up and running, and if you have a few minutes you write down everything you can remember you did before moving to the next project.

Kinda sad, because I've taken over multiple jobs where there has been VERY sparse documentation, and no one else knew the material. So I spent a lot of my personal time trying to unravel why things were done, and what hacks I could safely clean up.

I've forced myself into the habbit of journaling stuff as I work on a project now. That way at least I have a list of what did and didn't work. It gives me a clue 6 months later why I jumped throught those twenty flaming hoops instead of the easier route.

But even that.. There is only so much one can document as well.=(

- Ben

Still not mature enough?

Tuomo Stauffer's picture

Welcome to the weird world. Today most of large software companies IBM, Microsoft, Oracle, HP, etc have a good documentation. Some hardware companies also, IBM and Intel has mostly excellent, Cisco and other network hw companies not so much for some reason? And business system vendor documentation is mostly on executive presentation level because they don't want you to know the guts of their products. User, corporation, business entities lost the documentation idea sometimes in 80's. Before that it used to be decent but when all the short term performance requirements started documentation was the first to suffer, why do that, we know our systems? Maybe it is also because the use of SC/CM systems disappeared for a long time, I don't know. In late 70's documentation was hot, I built SC/CM systems where you had to have documents and write documentation or it just refused even to start without project and business documentation and/or refused save / compile code without documentation. Now, the quality was of course not always on par but then I, a project manager, QA or a system auditor did go after you! A dream to work on those systems, you could always refer to documentation. And a funny thing, I did find the same with resumes as you did, there really seems to be a shortage of document people.

I've been a Linux user since

Anonymous's picture

I've been a Linux user since 1998. I've worked as a C/UNIX programmer since before that. I do freelance Internet programming. But last week I began the switch over to Apple OS X.

Why'd I do it? Because the documentation available from the Apple Developer Connection is very good to excellent. The documents I've read so far have been accurate, well written and easy to find. After years of googling message board archives trying to find soultions to obscure problems, and often finding nothing, I found this too much to resist.

When they don't even bother

Anonymous's picture

When they don't even bother to make man pages for their own software half the time?

Thier documentation efforts are pretty limited....

Who's "they?"

Anonymous's picture

Who's "they?"

I was thinking about writing

Rudolf Olah's picture

I was thinking about writing documentation for open-source projects and this is a good warning. It is a large job yes, but only if you include the million or so half-dead projects that have fewer than 10 users.

Good thing I bought the Economist Style Guide and White & Strunk's Elements of Style :D

"Is providing Linux

Anonymous's picture

"Is providing Linux documentation an insurmountable task? I'm starting to think so."

I think it depends on the people who run a project.

We have trac, wikis, version control systems, good programming languages such as ruby and python.

All the tools simplify the process of providing documentation too, but there are some people who write
code, and no docu at all. Never.

I would wish these people would stop writing code (at least releasing that to the public so it would
die off and leave way for programs which provide docu ... ).

A project that is incapable of providing good quality docu, should not exist at all.

Another factor is that some key linux distributions do not want to be uniform.
They feel that, if they are different, they provide different advantages too.

And what do we now have? A huge mess. A FHS which is so ugly people dont even
question it. Same with LBS which is a plan too.. ah i stop this rant :)

Documentation for big programs is IMPORTANT. And some get it right!

Is providing Linux

SEIKO's picture

Absolutely true informations. Good article , Thank You. Marry Christmas