Re: When Worlds Collide: McConnell meets H

Subject: Re: When Worlds Collide: McConnell meets H
From: Janice Gelb <janiceg -at- marvin -dot- eng -dot- sun -dot- com>
To: danemory -at- primenet -dot- com, techwr-l -at- lists -dot- raycomm -dot- com
Date: Fri, 23 Jun 2000 10:54:26 -0700 (PDT)

In article ORG -at- lists -dot- raycomm -dot- com, danemory -at- primenet -dot- com (Dan Emory) writes:
>In the instance I was talking about, I maintained both the functional spec
>and the primordial end-user doc (hereafter called the primordial doc).
>Once The primordial doc is created, each is maintained separately.
>Each time I update the functional spec, any relevant updated info
>from there is also put into the primordial doc. This, of course, is much easier
>if both docs are in SGML or XML stemming from the same DTD/EDD,
>in which case attributes can be used to record revision info, as well as
>requirements traceability, and, in the case of the primordial doc,
>identification of the tasks which will ultimately have to be incorporated
>into the "real" end-user doc. As the project evolves, the primordial
>doc organically grows into the "real" end-user doc.

These seems like double work to me. Again, I still think
it's better to have a separate writer doing the spec.
Although the spec obviously has to keep up with the
changing product, I don't see why the user doc should
be maintained separately, even in a primordial way, until
the product is fairly stable.

We once figured out at a previous company at which I
worked that if we hadn't started seriously writing
user docs until beta, we still would never have missed
the ultimate FCS date of our products :->

>| >danemory -at- primenet -dot- com (Dan Emory) writes:
>| >It helps, of course, if the original functional spec,
>| >the primordial end user doc, and the "real" end-user doc
>| >are all structured docs (e.g., SGML or XML) which share a
>| >common DTD/EDD. That eases the process of reusing and
>| >repurposing the information, using FrameMaker+SGML as the
>| >authoring tool for all of them.
>| >
>| >Janice Gelb writes:
>| >
>|That's a *big* if!
>Why such a "big if?" The huge advantage of SGML and XML
> [snip]

My big "if" was not whether this would work well
in SGML and XML, but rather whether most companies
and writers are currently using these tools. The
original question was about an approach to doc design.

Janice Gelb | The only connection Sun has with
janice -dot- gelb -at- marvin -dot- eng -dot- sun -dot- com | this message is the return address.

"Politics is show business for ugly people" -- James Carville

Previous by Author: Re: When Worlds Collide: McConnell meets H
Next by Author: Re: STC Conference/PLEASE POST PRESENTATIO
Previous by Thread: Re: When Worlds Collide: McConnell meets H
Next by Thread: Re: When Worlds Collide: McConnell meets H

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

Sponsored Ads