TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Mark Levinson (mark -at- sd -dot- co -dot- il) wrote:
: Any feelings on SGML? Advantages, disadvantages?
: ** Disadvantages: It takes away your control over how the
: text looks and how the text fits on the page. It demands
: that you consider content without considering form, the
: message without the medium.
No. It demands that you consider content _separately_ from form.
Someone (the document designer) must make decisions up front about how
the document is to be laid out and presented. Once these decisions
are made, you are _guaranteed_ consistency. Such consistency means
higher quality documents and less work for your editor.
That's not to say that these decisions are cast in concrete --
your document designer needs to be flexible enough to implement
changes when they are necessary.
: It can lead to unrealistic expectations of portability
: (wow, we can use our brochure as the introduction to
: our reference manual, our reference manual as our
: training manual, our training manual as our online help...).
Maybe. I guess you are saying that people start to expect that the
same information can do triple duty without rewriting. That's not
SGML's fault -- you can make the same bad assumptions with FrameMaker
or Word. Remember cut and paste?
: And my specific pet peeve: If the importance of your
: headings is not really in strict top-down order, there's
: no way you can let the reader know.
: (That may bear explanation. Suppose, for example, that
: I am explaining functions one by one and that for convenience
: the functions are grouped by category. Maybe the category is a
: second-level heading and the function name is a third-level heading
: but I want the function name to jump out at the reader; that's
: what the reader is more likely to be looking for. I can't
: convey the idea that a third-level heading should be more
: prominent than a second-level heading.)
Sounds to me like your document analyst and/or designer did a lousy job.
If you have a manual section that describes functions one by one,
then whoever wrote your DTD should have taken that into account.
And you should be talking to whoever decided not to emphasize the
function name. These things are not cast in stone unless you have
an inflexible document designer.
: Advantages: It's sexy.
Actually, it's really not. SGML as a "language" (many people will argue
that it is not a language, and they have valid points) is pretty clunky.
: __________________________________________________________________________
: ||- Mark L. Levinson, mark -at- sd -dot- co -dot- il -- Box 5780, 46157 Herzlia, Israel -||
: || You can't judge right by looking at the wrong. - Willie Dixon ||
I think this .sig is particularly apt. It appears that you are looking
at an SGML implementation that was not particularly well thought-out,
and therefore are making judgements based on a bad example.
I don't mean to be overly critical -- I just think that you are
judging SGML strictly from the point of view of an author who is
working in an inflexible environment.
--
Glenda Jeffrey Email: jeffrey -at- hks -dot- com
Hibbitt, Karlsson & Sorensen, Inc Phone: 401-727-4200
1080 Main St. Fax: 401-727-4208
Pawtucket, RI 02860
