Re: text production process

Subject: Re: text production process
From: "Gary S. Callison" <huey -at- interaccess -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 03 Feb 2003 12:27:13 -0600 (CST)

On Sat, 1 Feb 2003, jqg -at- pc -dot- dk (John Garside) wrote:
> Mike Stockman wrote, in part
> | the original poster asked a question that just dripped with
> | management buzzwords, and didn't really ask anything meaningful.
> There's worse at
> "Identifying and managing critical business processes is a vital
> factor in the effective management of successful organizations. This
> appears to be a fairly obvious statement. At the heart of the business
> excellence model there is a strong beat generated by the emphasis on
> process management."

I realize that this may turn into a discussion pounding the sand where
once there was the gravel stained with the blood of what was once a dead
horse, but here goes: There's nothing wrong with trying to put some
procedures in place to aid in creating high-quality documents.

> | I've been a tech writer for over 15 years, and I've never even
> | encountered a "text production process." [...]
> Interesting.

Yeah. Makes me wonder where text comes from then. Magical document
fairies, attracted by the stale coffee left on your desk, come in at night
and type them?

> | the question itself seems designed to avoid actual work

Then you're doing it wrong.

> My problem is that work is _increased_ because each document means a
> new process; there is little standardised history to go on, argument
> and personality conflict abound, novices sink.
> "Processes convert inputs into outputs." But our inputs enter the
> process ad hoc -- at any point, at any time. The output isn't quality
> controlled.
> In a word, a kind of customer-dictated chaos.

I have the same problems. Software requirements change minute-by-minute,
demo code and UI mockups are often written before there's anything like
a formal software requirements document, and the information provided to
the programmers to generate the demo/mockup stuff doesn't actually include
things like "What's this software supposed to do?" This isn't "Extreme
Programming", this is "Impossible Programming".

So how do I deal with this? I have a text production process. Here's how
it works: I follow the Gospel According to Hackos. Someone drops a project
on me, the first thing I do is start to quantify what it is that they want
me to do, and get a general idea behind the concept of the thing they
want me to do it to.

Usually, it looks something like this. They want: 1) a software
requirements specification, 2) Usability documentation (a manual, a short
tutorial, a checklist, an installation guide, some combination of the
above), and 3) a software test plan. The thing they want me to do it to is
a software module that is supposed to accomplish business functions foo,
bar, baz, etc. They'd like to see a rough draft of the tutorial in a
week, a req doc in a month, etc.

Those things right there: list and format of deliverables, business rules
and high-level concept of operation of the product, and tentative release
schedule, that's the meat of the "Information Plan" deliverable that
Hackos describes in part 2 of her book. Bounce this off of the internal
customer, and they can tell you if you're going the right direction.
This is a good thing to find out before you've actually invested the time
in writing something that isn't what they want.

Next: research the details of the thingy being documented, and outline
the documents you're going to produce. Those details and outlines are the
Content Specification, Hackos part 3. Having an outline that makes sense
does a bunch of things, but the part of it I like the most is the ability
to look at the product, look at the outline, and be able to instantly
come up with an educated guess at how long the thing is going to take me
to write. This requirements doc I'm working on now? Three weeks, probably
be 75 pages or so. I should have the requirements for the first business
rule done in a couple days, check the 'DocDrafts' directory on the
development webserver, and let me know what you think.

Phase III: write. Both you and your customer have agreed on what exactly
you're writing (Phase I: "Information Plan") and how you're going to
write it (Phase II: "Content Specification"), so after blowing 25-35% of
your total project time on that pesky 'planning' horsehockey, now you can
start writing. Produce amazingly fabulous documents, show 'em to the
customers, and then Phase IV: review the process to see what can be made
to work better next time. If you do it right, this generally consists of
"Hey, you're amazing. We'd like to buy you a pony."

This is my text production process. It saves me a lot of time and
headaches, it makes the managementy and customery-types happy, and makes
me significantly more productive than when I used the "just start typing"


Buy or upgrade to RoboHelp X3 today and receive the WebHelp
Merge Module for FREE ($299 value). RoboHelp X3's all-new
features include conditional text, completely re-engineered
printed documentation output, Context-sensitive Help Toolkit,
single-source layouts, and more!
Order online today at

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: Computer Based Training
Next by Author: Re: TOOLS: quiet keyboard
Previous by Thread: RE: Are you using personas? (Take III)
Next by Thread: Re: Help! Need to reformat over 1000 *plain text* Word docs quickly

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

Sponsored Ads