Re: When Worlds Collide: McConnell meets H
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.
There is no double work involved. Obviously, the writer doing the
spec always has more current, complete, and accurate information
about the product than anyone else, and is in the best position to
(initially at least) create and update the primordial end user doc. At the
appropriate point, it can be turned over to another writer
for conversion to the "real" end-user doc.
======================================
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 :->
But then, of course, the Beta testers, particularly if
they're outside the company, have no documentation
to use during the testing. How does a Beta Tester
do a good job of flogging the product if they don't have
reasonably complete end-user documentation that
looks (more or less) like the final document?
Also, Beta testers, if they're good, are likely to find and report
serious errors/omissions in the documentation.
================================================
>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.
And my answer is that the issue isn't whether they're
presently using these tools, it's whether they ought
to be using them because of the enormous productivity
gains (as well as substantial improvements
in document quality, accuracy, and completeness)
which are possible. These gains arise from
the value of the metadata, and the concomitant improvements
in managing, retrieving, reusing, and re-purposing information.
====================
| 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 H
Next by Author:
Getting Rid of Unused Tags and Format Overrides in FrameMaker
Previous by Thread:
Re: When Worlds Collide: McConnell meets H
Next by Thread:
RE: being too picky?
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads