SGML & The Technical Writer

Subject: SGML & The Technical Writer
From: Pat Berry <pat -at- BERRY -dot- CARY -dot- NC -dot- US>
Date: Mon, 11 Apr 1994 19:04:08 EDT

Gerry Bourguignon <ad767 -at- FREENET -dot- CARLETON -dot- CA> writes:

> When discussing SGML with one of my profs at the college, he made the
> comment that many engineers look at technical writers as people who simply
> churn out text and really don't have to think much or concern themselves
> with how the information is presented.

Funny, that's how I think about engineers when I have to decipher a
functional spec written by one of them.

No, that's really not fair. Engineers have to devote most of their
efforts to developing products, and it would not be reasonable to expect
them to produce polished writing. That's not the best use of their
time. As long as the documents they produce are understandable, I'm
satisfied. Writers, on the other hand, have a much higher standard to
meet. Any "writer" who simply churns out text and doesn't think much
about how it's presented needs to start looking for another profession.

> He thought one of the main reasons
> many chose technical writing as a career was to be generalists rather than
> to be limited to one specific function.

I'll bet your professor really hates it when people say "those who can't
do, teach." :-)

Writing *is* a specific function. I didn't choose technical writing in
order to be a generalist. I chose it because I was good at learning
about things and explaining them to others, and technical writing was
the best way to make a career out of that. In other words, I like
teaching. :-)

> If writers don't have to concern
> themselves with document design or layout, then their jobs become reduced
> almost to a clerical function. He said that would be the day when he
> would do a job where he sat in front of a keyboard inputting text all day
> long.

> What do others think? Does SGML encourage this view? Does SGML
> threaten to turn writers into clerks? Will it put writers out of work
> altogether?

Absolutely not. Where does your professor think writers *get* the
"text" he envisions them "inputting" all day long? Does it matter to
him what that "text" consists of, or would he be just as happy if we
took random chunks of the Congressional Record, inserted SGML codes to
make it look pretty, and published that? (Deep breath.) Sorry, I'm
getting a little defensive about this. But it seems to me that your
professor has a rather simplistic view of what writers do.

Writers work with *information*. It takes knowledge, experience, and
expertise to evaluate an audience's needs, collect the appropriate
information, organize it, present it in the clearest and most usable way
possible, and enhance its value with tables of contents, indexes,
glossaries, and so forth. This is not a "clerical" function. Anyone
who thinks that is invited to hire a *real* data entry clerk to create
their technical documentation, and see if they are satisfied with the
result.

> In a popular introductory book on SGML entitled "Practical SGML" by Eric
> van Herwijnen, the author says: "Authors are subject matter experts for
> whom it is a waste of time to be concerned with typography or document
> layout. Some call it creativity, but inside organizations where the author
> has free reign over format the result is usually an incoherent collection
> of badly looking documents."

> Do you agree with this statement?

There is some validity to this point of view. It's simply the idea of
division of labor applied to technical documentation. If you expect the
same person to both write the document and also create the graphic
design for that document, you will naturally get less impressive results
that if you assign each task to a qualified professional. Besides, many
writers are not trained in graphic design; why are they expected to know
how to do it?

I spent several years writing manuals on contract at IBM, using their
BookMaster publishing system. BookMaster uses imbedded codes in much
the same way that SGML does, but the system is implemented in such a way
that there's almost complete division of labor between those who write
the documents and those who create the graphic design. You insert
BookMaster tags to indicate what things are (paragraph, heading, table,
note, etc.), not how they should look. The "look" of your document is
controlled by a style file, which is created by the graphic designers.

I found this approach to be quite liberating. It meant that I didn't
have to concern myself with fonts, or margins, or how things were
arranged on the page: I could concentrate on getting the words and the
organization right. The style file had already been created by experts
in the field, and my documents would automatically use that style
without requiring me to do anything. This also ensured that my
documents would be consistent in form and appearance with other IBM
documents.

I don't know if I would agree that typography and document layout are a
complete waste of my time, but I think my time is better spent writing.
If an expert graphic designer is available, I prefer to give that person
control of the graphical elements of the document and concentrate on the
content. If I have to do both, I'll give it my best effort, but the
graphic design won't be as good as what an expert could produce.

Whew! Time to step off the soapbox and let someone else have a turn.


Previous by Author: Sexist computing env's.
Next by Author: Internet and CD-ROM
Previous by Thread: Re: SGML & The Technical Writer
Next by Thread: SGML & The Technical Writer


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


Sponsored Ads