Re: When Worlds Collide: McConnell meets H

[Janice Gelb <janiceg -at- marvin -dot- eng -dot- sun -dot- com>]

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. 
http://www.geocities.com/Area51/8018/index.html

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