Technical writing in the development process?

Subject: Technical writing in the development process?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Melissa Nelson <melmis36 -at- hotmail -dot- com>
Date: Sat, 24 Jun 2006 23:07:09 -0400

Melissa Nelson wondered: <<I was wondering if I could get some responses about how you as a technical writer are involved in the software development process.>>

In a perfect world, we all (programmers, techwhirlers, et al.) sit down at the table with the marketing and sales managers when they get that certain sinister gleam in their eye, and we beat them to death with the Microsoft Manual of Style before they can escape the meeting room. Those of us who remain then do the carpenter thing: we spend a helluva lot of time figuring out what we actually want to do, make up some prototypes, test 'em, revise the prototypes, test 'em again, and ***then we freeze the damned interface for this version***. Then the techwhirlers start documenting and the programmers start programming, and everything gets done simultaneously, with realistic deadlines and no pressure to ship before the product is ready.

Oh... and did I mention that chocolate isn't fattening? And that Budweiser and Coors have finally decided to start making real beer, and will give it away for free for the next year to atone for their past sins? <gdrlh>

In the real world: <<I am not involved at all until the very end and then I find myself trying to do eight weeks of documentation in two or three weeks, as the developers tend to see a July 30th deadline as meaning they should have it done on July 29th. :) That is an exaggeration...but not much of one.>>

That's not uncommon, but another fact of life is that developers don't usually work on all the features simultaneously right up to the end. Usually, they finish a few things early, a few more things a decent length of time before the deadline, and a few final things at the last possible instant.

The trick is to start working on the first group of stuff, continue with the second group, and finish with the third group... which of course requires us to keep in ongoing contact with the developers to learn what is stable enough to document, what is stable enough to start thinking about and outlining, and what we shouldn't even bother with until the final days. In addition, we need to be in good enough with the developers that we can find out when they've stopped fiddling with the interface and are mostly playing with the plumbing that makes it work.

Learn that trick, and the rest is relatively easy... or at least not insanely difficult.

<<... this month there are three projects with the same deadline, which is the week of my vacation (which is to celebrate my Dads 75th birthday and can't be rescehduled)>>

"Planning? We don't need no steenkeen' planning." <g> Sympathies. When in this kind of situation, the best you can do is aim for triage: provide the essential information that users can't succeed without knowing, and if time permits, provide the stuff that will make the knowing easier. Forget about the details they can figure out without your help.

So if all you can fit in is an overview of a process, with no screen shots and only a vague resemblance to the actual product, too bad. No point killing yourself over a piece of software. Next time they'll at least pay attention when you tell them you need to be kept informed. Of course, next time you'll benefit from a few extra tricks that will make your life easier:

<<I have talked to the developers and while one or two of them seem sympathetic, the rest have an "I will give to you when I give it to you" attitude. I also understand that they work their butts off for the most part too, and anyone that is not a developer is viewed by them as support.>>

It pays to remember that programmers are rarely responsible for these problems. The real source of the problem is the (mis)managers who think that architects and engineers are wimps because they carefully craft a blueprint before starting to build. Their partners in crime are the Dilbertian marketing and sales managers who set deadlines without asking anyone whether those deadlines are even vaguely realistic.

There's a myth that programmers should be wild and free cowboys who work purely by inspiration and wild talent. Some of that is true; programming is still as much art as science. But the rest of this attitude is nothing more than intellectual laziness, and it's why so few programs work as intended and why something like 50% of all software projects fail. Careful planning and disciplined design (i.e., setting a feature list and sticking to it) is not a panacea, but it goes a long way to making software development survivable and effective.

The best argument I ever came up with for sticking to the original features: "If we give them everything now, then why ever would they buy an upgrade* in 6 months? Give them something with the features they really need, working perfectly, now, and sell them version 1.5 in 6 months--also with features they really need, working perfectly. Not only will you get a deserved reputation for knowing what you're doing--you'll also significantly pad the company's bottom line and get promoted. Bet you'd prefer that to the current chaos, huh?"

* As opposed to several free patches for the shoddy crap we pushed out the door before it was ready.

<<I would like to talk to my PM about it, as it seems a tad silly that I spend weeks trying to come up with ways to keep busy, including a ton of non-technical writer projects, and then pull my hair out and struggle to come up with documentation that I am not even very happy with.>>

If you're twiddling your thumbs, that's a really strong sign that you aren't paying attention to what's going on. Instead, spend that "down time" finding out what the final product is supposed to look like, and begin writing high-level documentation immediately. That can be as trivial as "the Print function lets you print one or more copies of different page ranges on different sizes of paper" or even "the documentation for the Print function goes here someday (this page not intentionally left blank)". But at least if you ship that particular bit of documentation, you'll be giving the customer something useful to read.

Meantime, keep in touch with the developers without being annoying. Where possible, figure out ways to help them (make their lives easier) so that they see you as an asset, not an ass. This can be as easy as helping them to type and correct the text strings that become part of the interface to taking minutes at their meetings so they won't have to do it. Some techwhirlers who haven't learned the fine art of industrial espionage consider minute-taking demeaning. My take is that you can't _buy_ this kind of information for any sum of money.

As the product begins to stabilize, you can flesh out (and correct!) that initial high-level information. And as things gradually stabilize, you can provide the final details. Those final details only come as you get progressively closer to the deadline, and that's when the developers start going a bit nuts--because their necks are on the line too, and they're going to be every bit as dissatisfied with the quality of their product as you are with yours. That's when you back off and stop being a nag, and start helping out--offer to fetch coffee for your bud working 24-hour shifts on the Print dialog next time you go for your own coffee, for example.

In short, get as much work done as youcan early, while making yourself an ongoing asset to the developers and part of the team. Not everyone will appreciate you, but those who do will return the favor when you need it most. Plus, it makes life at work that much more pleasant for everyone.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today!.
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.


Technical writing in the development process: From: Melissa Nelson

Previous by Author: Follow the following?
Next by Author: Technical writing in the development process? (take II)
Previous by Thread: Technical writing in the development process
Next by Thread: RE: Technical writing in the development process?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads