Re: When Worlds Collide: McConnell meets H
In article ORG -at- lists -dot- raycomm -dot- com, danemory -at- primenet -dot- com (Dan Emory) writes:============================================
>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.
>
>Janice Gelb writes:
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.
Yes, but an engineering writer who has the capability to write both
functional specs and end user docs can substantially
improve and accelerate the process of converting engineering data
into end user docs.
=========================================
danemory -at- primenet -dot- com (Dan Emory) writes:
>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.
>Janice Gelb writes:===========================================
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?
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.
In other words, the approach I'm describing is an implementation of
Integrated Logistics Support concepts, in which design information
logically evolves into end-user documentation.
==================================================
>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 is the
ability to keep metadata (in the form of element names and attributes)
within the documents themselves, rather than haphazardly in external
notes or somebody's head. And, there's nothing particularly difficult about
designing a DTD/EDD that accommodates many different document types,
all of which utilize a core of atomic and molecular elements that are common
to all document types. In such a DTD/EDD, the structural differences
between document types are implemented by "wrapper" elements that
are unique to specific document types. Since the core elements are
the same in all document types, you can convert one document type (e.g., a functional spec)
to another (e.g., an end-user document) by changing the wrappers and
doing some other rearrangements which are relatively easy to accomplish
with something like FrameMaker+SGML's interactive structure view
and element catalog.
====================
| Nullius in Verba |
====================
Dan Emory, Dan Emory & Associates
FrameMaker/FrameMaker+SGML Document Design & Database Publishing
Voice/Fax: 949-722-8971 E-Mail: danemory -at- primenet -dot- com
10044 Adams Ave. #208, Huntington Beach, CA 92646
---Subscribe to the "Free Framers" list by sending a message to
majordomo -at- omsys -dot- com with "subscribe framers" (no quotes) in the body.
Previous by Author:
Re: When Worlds Collide: McConnell meets Hacko
Next by Author:
Re: When Worlds Collide: McConnell meets H
Previous by Thread:
RE: When Worlds Collide: McConnell meets H
Next by Thread:
Re: When Worlds Collide: McConnell meets H
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads