RE: Single Source the cheap and dirty way

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

> -----Original Message-----
> From: Mike Starr [mailto:writstar -at- wi -dot- net]
> Sent: Saturday, September 08, 2001 12:55 AM
> To: TECHWR-L
> Cc: Andrew Plato
> Subject: Single Source the cheap and dirty way

<edited down> 
 
> I've always approached a software documentation project by 
> first creating
> as comprehensive a user's manual as possible. 
> I write all of this stuff knowing 
> full well that
> I'm going to build a help file out of it when I'm done so I 
> don't have to rewrite any of it.

Good tactic.
 
> When the manual's done... Now comes the
> fun part.... I apply a spiffy second template to a copy of 
> the Word file
> (AAACCCCKK, did he say Word??), export it as RTF and then 
> import the RTF into ForeHelp. 
> Now all I have to do is apply the context IDs, create the
> contents file and build the browse sequences. Voila... total time to
> repurpose a 300-page comprehensive user's manual into a 
> comprehensive help file?? Three or four days. 

I realize that you said this was approved by the pointy-haired boss
prior to making this leap. Alas, what happens when the whiz-kid
programmer decides that they want something impressive for their review,
so they go ahead and implement some below-the-line features (as in, not
in the must-have above the line wish-list items for this release)? They
demo it with the pointy-haired boss; it doesn't impact QA too much.
Before you know it, the PHB is on the whiz-kid's bandwagon. After all,
the company gets more features for the release than originally expected;
makes him, the department, and the whole company look better.

Then, not only do you have to write the content for these new whiz-bang
features at the tail-end of the release, but you also have to do the
three or four day manual conversion again. Moreover, you have to do this
conversion each release or each time something changes that you can't
localize and compartmentalize to avoid too many tweaks to both print and
online (just to be safe).

This is where tech writing really needs to take a lesson from
engineering. Engineers never do anything twice; if they find themselves
doing it twice (to their girlfriend's dismay :), they write a routine.
{Sorry about the parenthetical joke; I just couldn't resist. :) }

Mike, you said that from the onset you knew that you were going to
re-purpose the stuff you wrote which affected among other things the
number of headings you used. Going this manual-route for the first
release might be indeed the way that I would go, just to get it out the
door.

Well on the way to the second release, I'd be looking at this process
and saying to myself "I don't want to be manually applying those damn
context IDs again over three to four days at the end of the release."
I'd be looking into a tool to get it done. You said yourself that you
already have some tools and templates to expedite the process, so you've
already started down this path. 

Somewhere in the down-time early in the second release cycle, I'd be
tweaking the process and trying to get the content IDs and other online
only tags into the source (although not visible for print/PDF). Maybe
creative use of hidden text, colors, and macros in Word (if I wasn't
already using FrameMaker and Mif2Go).

> And I can do it in that short a time because I'm
> already intimately familiar with every topic in the help file 
> because I've been living with it in the form of the manual. 
> I know the stuff cold and I
> don't have to fiddle around trying to figure out how to put 
> it all together.

Ah, yes. Mike, _YOU_ know the stuff cold. "But if you can't be replaced,
you can't be promoted." Does your new co-worker who was hired to offload
you so you could work on some whiz-bang project know it cold too? If you
never do the manual export again and choose to maintain two versions of
the text (print and online), are you/they going to be as diligent in
always updating both for all later changes?

"Single-sourcing" might indeed be a buzzword worthy of Andrew's rant.
However, "document maintenance" is another catch phrase that is not so
easily dismissed. Andrew mentioned that he has some repeat customers;
however, Andrew has done lots of one-of projects where his firm did the
docs and then threw it over the fence for the in-house personnel to
maintain from then on.

Document maintenance is where the right process from the start (or on
the way to the 2nd and 3rd releases) can begin to save your behind.
Quick and dirty isn't quick in the long-run and remains dirty.

I mean, your 3-4 day tweaking was what I needed to figure out FM with
Mif2Go. The difference is that I only did it once and from now on need
less than 1/2 day for each project/release; you theoretically have 3-4
days work at the end of each release and project to re-generate the
quality output. I can spent that time on last-minute content,
re-generate the quality output in 1/2 day, and still be the hero.

 
> So, yeah, I can't just click a button and build a help file 
> but given that I probably would have had to invest in multiple 
> thousands of dollars of software 

FrameMaker + Mif2Go comes in right around a grand.

> and spent weeks upon weeks learning it and still 
> more weeks upon weeks trying to make it work, 

Aside from being an overstatement (it's more like a week to learn it, a
week to make it work the FIRST TIME, and a day to make it work for each
new product or 1/2 a day to make it work for each release of a given
product), your proposed solution is: "a week no matter what for each
product and each release trying to make it work."

> I think I've come out just fine. And the
> bottom line... my clients have been mightily pleased with 
> that approach as well. One recent client's comment... "We've gone from
no 
> documentation to having the best documentation in the industry." 

Sounds like you're throwing it over the fence for your client's in-house
technical publications department to maintain from then on. If you're an
outside contractor who is paid by the hour only for the hours worked,
this is indeed a good solution. A true single-source solution by someone
inside who is paid no matter what just as long as they meet the
schedules is better; less stress at the end of the release, less tedium,
possibly more time for meetings and other things...

Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.  http://ieeepcs.org/2001/

  +++  Miramo -- Database/XML publishing automation.  See us at  +++
  +++  Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion  +++
  +++ More info: http://www.axialinfo.com  http://www.miramo.com +++

---
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
http://www.raycomm.com/techwhirl/ for more resources and info.