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: techwr-l -at- lists -dot- raycomm -dot- com
Date: Fri, 23 Jun 2000 09:17:03 -0700 (PDT)

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.

Previous by Author: Re: When Worlds Collide: McConnell meets Hacko
Next by Author: Re: When Worlds Collide: McConnell meets H
Previous by Thread: Re: Piracy: Home vs. Work Computers
Next by Thread: RE: When Worlds Collide: McConnell meets H

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

Sponsored Ads