TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
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!. http://www.webworks.com/techwr-l
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList
