Log in

Previous Entry | Next Entry

There are four lights.

Years ago when I was a technical lead for a documentation group, I used to say to new technical writers that there were a few stages in the progress of a new technical writer at our company:

1) "I have no idea what anyone is talking about" -- This phase sucks, and the only thing I can say to make it better is that it happens to everyone, it doesn't mean I'm any more of an idiot than the rest of us.

2) "I know what people are talking about, but I don't know what they're saying." -- This is huge progress, since it lets me ignore the 99% of what people are saying which isn't about the subject I'm trying to understand right then and concentrate on the 1% that is.

3) "I know what people are saying, but I don't know why it matters" -- This is again huge progress, since it lets me ask sensible questions and focus my attention on the portion of the subject I don't yet understand.

4) "I know what people are saying and why it matters, but I don't know if it's true" -- Again, huge progress, since this lets me prioritize assertions within my area of interest.

And, I would add, it never actually gets any better than that; there really isn't a fifth stage. In stage 4 I'm considered a subject-matter expert and people ask me questions, which I answer to the best of my knowledge and everyone seems happy, but I'm never quite sure any of what I just said is true.

Some people appreciated this, others didn't. The latter group seemed far more justified, but the former group tended to be more successful.


( 12 comments — Leave a comment )
Jun. 25th, 2014 10:51 pm (UTC)
"Is it true?" isn't in scope for tech writers, that's the test team's problem. The dev docs are concerned with what's SUPPOSED to be true, and it's the test team's job to verify that. The ops docs (specifically, the helpdesk knowledgebase) are concerned with what's actually happening, irrespective of whose notion of truth you're using.

That said: the training video I just made ends with this slide: https://mondaybynoon.com/wp-content/uploads/xVyoSl.jpg
It's a 300-person project that's been working for a year and a half and generated some 3,000 documents and millions of lines of code, and I've only been on it for five months.
Jun. 26th, 2014 01:57 am (UTC)
(shrug) Sure, if the environment is such that false information in the user docs will be attributed to the test team, then "is it true?" can be left in the test team's hands. That wasn't the case in this particular company; the tech writers needed to do more proactive investigation. (This is one of the reasons that most of the writers in that team later moved into more technical roles.)
Jun. 26th, 2014 04:22 am (UTC)
We're very 'agile', which near as I can tell means "in a turd farm". So there's approved requirements and wireframes and user guides and training videos, and all of those things describe the alleged truth. And I don't really care what that is; I was hired to write the helpdesk ops manual (which within three weeks on the job somehow changed to "admin the helpdesk's wiki") so all I care about is what actually happens.

It's like the old joke about dating, "not looking for Mr. Right, just looking for Mr. Right Now". I don't care about the right answer, I care about the right now answer. ...because that could possibly change in the build that drops next week.
Jun. 26th, 2014 06:06 pm (UTC)
In an ideal world, I would agree with you 100%. Tech writers should be fed 100% true information from the developers as features are being developed so they can focus on conveying that truth to users in terms they can understand.

The reality, however, is almost entirely different. In my experience, tech writers spend 99% of their time running around frantically like beheaded chickens, trying to confirm or deny the nature of any given feature in the next release.

In the lopsided caste system of the software world, developers rule supreme and everybody else (doc, release engineers, sysadmins, etc.) rank a distant 10th.

This is changing though, with agile methods becoming more commonplace, and the dev-ops movement gaining traction, organizations are realizing that emphasizing one piece of the team and ignoring all others is NOT the way to run a ship.
Jul. 1st, 2014 01:17 am (UTC)
In our shop, 'release manager' is the next step up from 'coding team lead', so they know what the deal is, and set schedules and releases based on "In the next code drop, I need these six defects fixed, plus whatever else you can get to out of this list, by Friday". And then the tentative release notes for the Saturday build are "includes these six defects, possibly more, updates to follow". Devs don't run anything but code and unit tests.
(Deleted comment)
Jun. 26th, 2014 02:00 am (UTC)
My email is my LJ name at gmail; drop me a line.

That said, I haven't been a tech writer in over fifteen years, so my knowledge may be woefully out of date.
Jun. 26th, 2014 01:44 am (UTC)
I will add, as a tech writer of some experience -- the faster one can power through stages 1-3 in any hi-tech company, the better off you'll be.

Furthermore, if you find that you can't get past stage 2 in less than 6 months, you'd be better off leaving and going to another company where you can. (I've met so-called "senior" tech writers who are in this boat. It's infuriating when I'm the person trying to boost them to stage 4 in as little time as humanly possible.)

Edited at 2014-06-26 01:45 am (UTC)
Jun. 26th, 2014 02:19 am (UTC)
You know, that might describe just about any job's learning curve if you think about it. It certainly describes mine.
Jun. 26th, 2014 06:24 am (UTC)
Sounds like the learning curve for ops, too, except along the way -- often in stage two or three, ideally on a test system -- you're up to your elbows in the system you're learning about, and likely griping about the errors in the documentation. If things work well, some of your griping is coherent and addressed to someone who's positioned to fix the documentation ...
Jun. 26th, 2014 05:51 pm (UTC)
It kind of sounds like grad school.

Hmm. Stages 3 and 4 are sometimes reversed. First, "I know what they're talking about and I know why it might matter, but I don't understand what they're saying about it," and only later do I (usually) figure out what they're saying about it. Sometimes I'm not convinced they understand what they're saying about it.
Jun. 26th, 2014 06:01 pm (UTC)
I suspect the reversal of 3 and 4 is a systemwide difference between being a student and being a knowledge worker... as a student, there's an a priori assumption that if I'm being told about something, it matters. As a worker, that just ain't so.
( 12 comments — Leave a comment )

Latest Month

February 2017


Powered by LiveJournal.com
Designed by Taylor Savvy