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:
>At 01:02 PM 6/22/00 -0700, Janice Gelb wrote:
>|My immediate response is colored by the fact that I
>|have mainly worked in large organizations. That said,
>|my feeling is that if they want someone to write a
>|functional spec, they should hire or assign someone
>|to do that. Obviously, the spec needs to be written
>|early because so many groups depend on it to do
>|their own jobs, and the engineers themselves should
>|have it to write the code against.
>|
>|However, specs are not user's guides. The reason Hackos
>|recommends that writers not write detailed information
>|for the end user in early stages of the project is that
>|nearly all of it will have to be rewritten as the
>|product changes.
>==================================================
>Nevertheless, a qualified engineering writer who produces 
>a functional spec early in the program, and who can also 
>write end-user documentation is likely to produce a more 
>usable functional spec, and that spec can be used from 
>the outset by the end-user documentation group as a
>point of departure. 
>

I agree that a qualified writer who can also write 
end-user documentation is likely to produce a more 
usable spec. Nothing I said above disagrees with that. 

>
>In fact, when I've been responsible for producing both 
>functional specs and the end-user documentation on the 
>same project, I continue, as the project evolves, to 
>update and expand the functional spec to serve as a 
>repository of information that will be needed in the
>end user docs. At the appropriate point in the 
>development process, this primordial end-user doc is 
>reorganized to become the initial version of the 
>actual end-user doc.
>

I can see where the spec would be a repository of information 
needed in the end-user docs. However, the approach of 
end-user docs is usually quite different in tone and 
organization than a spec (for example, specs don't 
usually include tasks, whereas that's mostly what's 
included in end-user docs). Also, does someone else 
take over updating the spec when you move over to 
concentrating on the end-user documentation?

>
>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.
>

That's a *big* if!

***********************************************************************
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