Single Source the cheap and dirty way

["Mike Starr" <writstar -at- wi -dot- net>]

While I agree with Andrew that there are many who would spend huge amounts
of money and devote an enormous amount of writer-months to cobbling
together a single-sourcing solution, I've done it the cheap and easy way
several times and I'll continue to do it that way as long as I'm permitted.

I've always approached a software documentation project by first creating
as comprehensive a user's manual as possible. That means I put together
descriptive text about the product and the way it functions, procedural
text that describes as many common procedures as possible and complete
reference text that describes every menu item and control in the interface.
I'm not afraid to admit in public that I sometimes use many more heading
levels than the conventional wisdom insists are appropriate for "quality"
documentation, but the end result is that when I'm done, every control in
every dialog box and every menu item or toolbar button will have its own
distinct chunk of text. 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.

When the manual's done and been blessed by whatever pointy-haired-bosses
and powers-that-be run the show, I create the PDF version of the manual and
(if necessary) the Postscript output for print production. 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. Every heading in my document becomes the title of a help
file topic. 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. 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.

I do have to join Andrew in saying that the writer needs to know the stuff
inside out. I don't just sit on my ample keister waiting for some
subject-matter expert to hand me bits of the manual. I get in there and
learn what the product does and how it does it and WHY it does it. I learn
it by playing with the product, making the stupid mistakes a clueless
newbie makes, by asking the same stupid questions and by prying the
information out of every nook and cranny of the organization, sometimes
making myself a godawful pain in the ass in the process.

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 and spent weeks upon weeks learning it and still more weeks upon
weeks 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." I told him "Do me a
favor... put that in writing, will ya??" He said "You bet."

Mike

---
Mike Starr                            WriteStarr Information Services
Technical Writer  -  Online Help Developer  -   Technical Illustrator
Graphic Designer    -    Desktop Publisher   -       MS Office Expert
Office:  (262) 694-1028 - Pager: (414) 318-9509 - Fax: (262) 697-6334
Home (262) 694-0932 - mike -at- writestarr -dot- com - http://www.writestarr.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.