Fog Creek Software
Discussion Board




The importance of good documentation people

A post by w.h. in the "Salary Issue" thread got me thinking about my feelings with regards to documentation in the technical field.  I'm a technical writer part-time and a programmer part-time.  I feel like Rodney Dangerfield when wearing my technical writing hat, and I'm confused about why technical writing is in the position it's in.

Let's start with a few propositions.

1.  Every technical product needs good documentation for its users.

2.  Good documentation is hard to write.

3.  Programmers don't like to write documentation, and even when they do, they often don't know how to write documentation that's comprehensible by a non-programmer.  Moreover, many programmers these days are non-native English speakers who (through no fault of their own) don't have the considerable command of the English language needed to write good documentation.  (I'm sure that some non-native English speakers can write good documentation; I'm just saying that many cannot.)

Okay, assuming that the above is generally true, I don't understand the following behavior, which I've observed everywhere I've worked:

1.  Technical writers are among the first to be eliminated from a project, and there are typically very few technical writers in a given organiziation.

2.  Programmers are often assigned to write the documentation for their own work, especially when the company's laying off workers.

This seems like madness.  So, why don't technical writers have more respect, or at least a larger presence in technical organizations?

Brent P. Newhall
Thursday, June 20, 2002


Simply Put:

Nobody wants to pay for documentation.

Backup. Rewind.  Read that one again.

Software Developers produce code; code has apparent business value.  Documentation does not except in the scope of a "whole package."

Which makes it a cost center.  Just like Tech Support.

In other words, it's like Microsoft's free pop - if it weren't for Microsoft's coder-centric culture, sometime in the 1980's some executive would say "WE are spending $5,000 a DAY on SODA!" and kill that program, then remark on his annual evaluation that he personally saved the company saved $1.8 Million in Pop.

Of course, the Cola added business value through free overtime and decreased turnover, but he wouldn't measure that.

The problem isn't just Tech Support - Check out Joel's Website for the false economy of eliminating full-time testers and instead having coders test ...

THERE ARE ways around this; the easiest way is to metric-ise yourself:

(1) Find a way to measure effort in "units"
(2) Figure out how many units you output in a given time.
(3) Divide your total cost over that period by output.  That gives you "unit cost"
(4) Tie your output to business value.
(5) Track 1-3 dilligently over time.  If they work, you can justify training, cola, software, hardware, time off - whatever.  If those things don't pay off, chalk it up to experience - at least we only "wasted" that money on me once, not the entire department once a year for 5 years ...
(6) Most importantly, if you can tie yourself to business value, you can justify yourself.
(7) If your company is stuck in the short-term mentality of
eating the seed corn ("Sending everyone to java training will kill February's P/L statement!" or "We can't afford tech writers!  It'll be cheaper to just have the coders write in  thier spare time ..." ), go work for somebody else. 

If the problem is a maturity issue (the company is 3 months old and ONLY employs three programmers) the problem is going to be different than a big, old company trying to save a buck, so YMMV.

regards,

Matt H.
Thursday, June 20, 2002

> Let's start with a few propositions

True.

> Okay, assuming that the above is generally true, I don't understand the following behavior, which I've observed everywhere I've worked: [...] This seems like madness. So, why don't technical writers have more respect, or at least a larger presence in technical organizations?

There are several kinds of "technical writing": sales brochures, end-user manuals, software requirements and design, ...

Writing the end-user manual is usually a contract position (in my experience): because it doesn't happen often (1st release); and because updating the manual takes less time than updating the software (on a subsequent release); and because technical writing (which may include translation) is a specialy niche ... and the contract positions are often terminated before the full-time/permanent employees ... sometimes you can keep a technical writer full-time, by giving them development (project management) or testing (QA) work in addition to their writing manuals.

Some of the technical writing (sales-oriented and development-oriented) is perhaps best done by an appropriate domain specialist (Director of Marketing, or Software Developer) and not by someone whose expertise is technical-writing of end-user manuals.

Technical writers who want to stay employed should broaden their domain expertise (know the software and/or the market).

I used to contract as a technical writer, and moved into development for some of these reasons. Being able to do both (technical writing or software development) at need helps to keep me fully useful.

Christopher Wells
Thursday, June 20, 2002

Being a technical writer means more than just having good written English skills.  You also have to be able to extract information from people who think they have better things to do than talk to the tech writer, and you also have to be able to grasp the topic material, which makes having a technical background very useful.  I don't think many companies get that, which is why they hire clueless English majors who churn out unhelpful documentation "click the XJB2013 support box if you wish to enable XJB2013 support".  These are the folks who are predictably the first up against the wall when the layoffs come.

I prefer to write the documentation for what I work on.  It's usually quicker to write and of much higher quality than if someone else were to do it for me.  But perhaps I'm an anomaly for being one of the few programmers who also likes to code in English.

Alyosha`
Thursday, June 20, 2002

This is exactly why literate programming is so important to us. Developers need to spend their time wisely and writing documentation could be done easier if a lot of it comes directly from the code. Java uses JavaDoc to produce help files documenting the class hierarchy. C# uses the xml comment structure to produce xml documentation, which can then be turned into easy to read HTML files or .chm help files using tools such as NDoc. Obviously not all aspects of a program can be determined from it's API documentation but literate programming does ease the pain and takes us in the right direction.


I would like make a note on from a comment above:
<snip>Software Developers produce code; code has apparent business value. Documentation does not except in the scope of a "whole package." Which makes it a cost center. Just like Tech Support.</snip>

If you look at the leaders in this industry (such as Microsoft)you will see that they look at tech support as a way to generate revenue instead of as a current expense, which a lot of other companies do. Support does not have to be a black hole and can actually generate revenue, especially using subscription based support. At least for shrinkwrap software this can happen, the same probably isn't true for internal IT departments.

Documentation can also be sold, as Oracle proves with their oracle press, as does MS with their MS Press, etc. This is a gray area where the line between simple user documentation/help and "training" tend to blur but it can also generate revenue. Documentation adds value to a product and that can be used to leverage it above your competitors.

Ian Stallings
Thursday, June 20, 2002

I agree that, if the coder has a good grasp of the English language, he or she is the best person to write the documentation.

For the first draft.

I have become convinced that having a technical writer to rework the documentation is a very valuable thing. For one thing, the coder is often too close to the system. Someone else can ask the questions:

"Why does it work this way?"
"Why can't we do it this way?"
"How can I make it do this?"

The person who coded the system either knows why already or hasn't thought of the question yet. Either way, it's likely not to make it into the documentation.

Where I work, I used to write most of the documentation (when I started, we had me doing software, one hardware engineer, a receptionist, and a part-time technician). When we got large enough to have a tech writer on staff, I started writing only the first drafts. The tech writer would take over from there, and all I'd have to do from that point would be to answer her questions and review her changes for technical correctness.

Want to measure units of productivity that can be assigned to a tech writer? Note how many tech support questions come in per unit time, then see if it changes after a tech writer has reworked the manuals. I know I see a lot fewer questions now than I used to, and almost none of the "new user getting started" issues. I haven't quantified it in terms of questions/week, but I have the support logs to do so if it became necessary.

Steve Wheeler
Thursday, June 20, 2002

I agree with Steve, actually.  I think my earlier post gave the impression of "tech writers, who needs em!?" instead of what I meant to say: "tech writers need a superior skill set than the mere techie".  Consider them as QA testers for your English text.  Most folk consider QA testers as somewhat below the "real engineers", but in reality they have to be better programmers than your programmers in order to do an effective job.  Same thing with tech writers, they're there to make sure you haven't left anything out, that you haven't bothered the user with irrelevant detail, and that correct grammar, understandable language, and a consistant style is used throughout.

<<For one thing, the coder is often too close to the system. Someone else can ask the questions:

"Why does it work this way?"
"Why can't we do it this way?"
"How can I make it do this?">>

I fear nothing more than the techie that doesn't ask himself or herself, "why did I code it this way and not some other way?"!!  Engineers that don't ask this usually wind up churning out reams of brain-damaged code.

What I'd usually expect from programmers working too close to the system is a deluge of reasons for the design and usability choices they made.  Programmers tend to be too detail-oriented and love to talk your ear off about how intricate and clever their designs are, when all the user needs to hear is "it improves performance", or the like.

Alyosha`
Friday, June 21, 2002

If you start a project with writing the specs as if you were writing the user manual, you are more likely to get at least the following two things.

1. a usable product, and
2. a usable manual.

Of course you require people who can think about the product from a user's point of view and not be distracted by technical issues where they do not matter yet.
And who can write coherently.

The developers can use that as a basis for design, manual writers as a basis for the final manual.
And if you keep things consistent throught the project, your chances of a succesful product AND project are so much better.

Erik

Erik van Linstee
Friday, June 21, 2002

Aloysha responded to my comments:

For one thing, the coder is often too close to the system. Someone else can ask the questions:

"Why does it work this way?"
"Why can't we do it this way?"
"How can I make it do this?"

With:

I fear nothing more than the techie that doesn't ask
himself or herself, "why did I code it this way and not
some other way?"!! Engineers that don't ask this usually
wind up churning out reams of brain-damaged code.

I would also expect programmers to know why they coded something one way and not another. Reasons like "it's faster", "it's smaller", "customer requirement X dictates this method" and so on.

What I'd usually expect from programmers working too
close to the system is a deluge of reasons for the design
and usability choices they made. Programmers tend to be
too detail-oriented and love to talk your ear off about how
intricate and clever their designs are, when all the user
needs to hear is "it improves performance", or the like.

Well, I don't deal with desktop or web software; I'm responsible for a Basic that runs on a PIC processor. I was thinking of questions more like:

"Why is the syntax different between this operation and that operation?"
"Can we do this with the system?"
"How can the user change the baud rate?"

In my experience, the technical people don't usually provide too much extraneous detail; they're more likely to presume too much background knowledge on the part of the user ("What do you mean, we have to explain hexadecimal numbers?")

Steve Wheeler
Friday, June 21, 2002

You also have to define what you mean by documentation people. When you state that all technical products needs documentation, are you not talking about a user manual?

A user manual can certainly document a product, and how to use the product. This might be a software product, or a new automobile.

The user documentation might even be some fairly extensive documentation on how to use a new Rage graphics video card. It might include code examples on how to use certain functions of the graphics card. However, that documentation will not include the internal source code, Nor will it real how the internal functions of the card work.

In most cases, the user documentation for a accounting package does not need to be written by a technical person. If you don’t make a distinction of the kind of documentation you are talking about, then this certainly will be a issue as to why, or why not the technical writers get laid off first.

Thus, this distinction makes it clear as to why technical writers are often the first to be eliminated in a company. If they are writing needed user manuals, then they can’t be eliminated, since that document is needed before the product goes out the door.

However, if you are talking about code, and software documentation (not for the end user), then you have a different issue here. Since many developers do not like writing good documentation for their work, many good companies as a perk hire technical writers to eliminate this drudgery. When things get tight, then the perks go away. Now the developers have to take up this slack, and write their own documentation.

Technical documentation of a automobile is something that then end user never sees. Even the people working at dealer probably do not get to see the source code, and documentation for all of the embedded systems (and there is a lot of software in cars these days...even some for just how the rear view mirror dims). However, that stuff does need to be documented for other developers. In a pinch those writers can be tossed out the door, and the consumer will never know the difference. It just means that the next developer looking at the code will have a bit more difficulty in maintaining, and modifying this code.

Albert D. Kallal
Edmonton, Alberta Canada
Kallal@msn.com

Albert D. Kallal
Saturday, June 22, 2002

Brent, I think good writers are as important as good software engineers. For what it's worth, I think the important thing is to be confident in your role and your worth, because then people usually treat you that way.

Hugh Wells
Tuesday, June 25, 2002

*  Recent Topics

*  Fog Creek Home