March 18, 2002

Today, I documented a feature that doesn’t even have a name yet.

Work tired me out. There’s a tremendous amount of work to be done there, and I used up every ounce of my psychic strength dealing with it all today.

I’m not tired by the work itself. Much of the stress lies in the difficulty inherent in technical documentation. Technical writers are normally expected — expected — to write complete and clear end-user help about features as those features are being implemented. For some reason, some people seem to think that a documenter shouldn’t even need a stable system; as long as s/he can access it (and s/he is assumed to have the technical competence of a developer to set up their machines properly), the documenter should be able to intuit a feature’s eventual full level of functionality based on half-working software.

This wouldn’t be too bad if our standards weren’t so high. Our help is supposed to be clear and concise to a non-technical user, and it should completely describe the feature, including any caveats and potential problems. Yet the developers are consistently surprised when we ask for an explanation of their work. Then they’ll rattle off a list of half a dozen potential pitfalls for users. How can we write good documentation if we don’t have detailed information about the software’s implementation?

Even this wouldn’t be too bad if developers only behaved like this once or twice, but the behavior I describe is depressingly consistently. Some developers are better than others, of course, and some are becoming more aware of our needs. But the mindset, in the main, remains.

This problem is compounded by the fact that, for most technical writers, “writer” describes them much better than “technical” does. Most technical writers are not exactly hot-shot programmers; they’re English Lit. majors. It’s almost impossible for people who lack technical skills to document a feature that’s still in alpha, that doesn’t even really work yet. Sure, any geek could figure it out, but documentation teams don’t have geeks in them.

Where am I going with this? I don’t know. I’m frustrated by a certain thoughtless mindset on the part of some of my coworkers. This puts me in an extremely frustrating and stressful position, where I’m struggling to piece together work that’s only half-explained.

And I haven’t even the faintest idea of what I can do about it.

(Footnote: I should point out that every individual developer at Intersect has been courteous and helpful. My frustration is caused by a mindset, not one or two people.)

Well, here I am, back at Intersect. It feels strange. I’m glad to be here, but…it’s not the same as before. I’m a contractor, which by necessity means that I’m a bit of a social pariah. Nobody will be working with me except to give me brief assistance or information, except my boss. So, while people are friendly, they’re still not quite the same.

I will point out that MegaTokyo is moving in a satisfyingly dramatic direction again, and 1/0 is taking some interesting twists.