RE: Single Sores

["Roy Jacobsen" <rjacobse -at- microsoft -dot- com>]

Definitely much good discussion on this. Andrew's list of questions is a
good place to start if you're asking "Is single-source a good idea for
my situation?

A couple of points:

>1. Do we have a lot of time (months perhaps) to design, test, and
enhance a complex SS system? 

You left out RESEARCH. There are many ways to skin the single-source
cat. Different tool sets fit different situations. And they don't have
to be complex, although some are.

>2. Is the content of the documents: 
>
>   a. Stable, that is not prone to wild changes in tone, direction, or
basic content?

Is any technical document stable? :-) But you do need to consider how
much instability you need to cope with.

>   b. Lend itself to a high degree of organization?

I think a good many technical documents--if not all--could benefit from
a high degree of organization.

>   c. Straightforward, that is not requiring extensive audience
education?

I'm really not sure what you're getting at here. Could you elucidate?

<snip>

>4. Can it produce a tangible benefit down the road that will save money
and 
>time without negatively affecting the quality of the material?

My initial reaction to this was "Well, duh!" However, in the real world,
ROI is all to often an afterthought.

>5. Are we able to adequately generate documentation using "traditional
methods?"

Are you getting at "If it ain't broke..."? If so, I don't necessarily
agree. Just because it ain't broke doesn't mean it can't be made
significantly better.

<snip>

>One of my problems with SS is the distillation of information. It has a
tendency to 
>reduce the overall conceptual cohesion of a document. SS docs often
read in a 
>herky-jerky manner because the chunks of information were written by
different 
>authors, at different times, with different levels of skill with the
content. 

Careful editing and a good style guide can work wonders.

>I've looked into numerous tools used for SS. Many are crude. Plain and
simple, 
>they have terrible interfaces, esoteric commands, and bizarro usage. 

You mean like MS Word? <VBG> I don't want to get into tool wars. I
haven't seen many techwriting tools that didn't have some characteristic
you mention above, to varying degrees. It's different horses for
different courses. A friend of mine worked in a Unix shop, writing man
pages and C programming manuals. They did the writing in vi, and they
had a guy in shop who created a set of scripts to create the man pages
and manuals AND compile and verify the code examples in the doc, all
from a Unix command line interface. Terrible interface, esoteric
commands, and bizarro usage. But very effective in that situation.

Regards,
Roy M. Jacobsen
Senior Editor, Documentation
Microsoft Great Plains Business Solutions
One Lonetree Road
Fargo, ND 58104-3911
USA
rjacobse -at- microsoft -dot- com

What this country needs is more free speech worth listening to. --
Hansell B. Duckett


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

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.