Re: Structure vs Substance?
Is structured information good, useful, and joyous to behold? Sure. But
what I think I've heard Mr. Plato saying, and what I firmly believe, is
that the people who place structure *before* content are damaging the
product, the user, and the reputation of tech. writers everywhere.
Why this dualistic, either or, chicken and egg mentality? What do you
mean by structure before content? The development of structure must
always be driven by content.
I once contracted, long-term, for a very, very damaged company. The doc.=================================================
manager who came in to fix things imposed standards, structure, more
standards, processes, and rules, and did a wonderful job of which any
Tech. Writing Certification instructor would have been proud.
The only problem was that the documentation was and had always been
wrong, inadequate, and difficult to use, and nobody was addressing that.
Structure, standards, etc. did *nothing* to perform our primary purpose
(and some might argue only purpose) in writing documentation: getting
useful information into the hands of those who need it. Always put
Once again you seem locked into the idea that content must come
before structure. What I'm talking about here is document structure,
as defined in a DTD, not organizational structure. A well-designed
DTD must be based upon analyses of content and requirements.
And by the way, you mentioned all the things the new doc manager did
right to try and fix a dysfunctional organization, but you didn't
mention what additional managerial actions he should have
taken to improve the existing documentation. The managerial
question would have to be: In what ways is the existing
documentation bad, how did it get that way, and what steps
must be taken to improve it? I would say, more often that not,
documentation such as you describe ("wrong, inadequate, and
difficult to use") is that way precisely because nobody gave any
attention to document structure.
| 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.
Search our Technical Writing Archives & Magazine