tech writing and SGML

Subject: tech writing and SGML
From: Liora Alschuler <LIORA -at- DELPHI -dot- COM>
Date: Tue, 12 Apr 1994 13:08:37 -0400

Questions and assertions have come up with increasing
frequency lately regarding the role of the technical
writer in an SGML-based production environment. The
recent discussions can be characterized by several,
sometimes contradictory, assertions and assumptions:

1.* the writer should/should not be concerned with
"representation" (read: format tagging or structural
markup);
2.* the writer should/should not be concerned with how
things look;
3.* the writer is/is not/should be/should not be
constrained by writing in an SGML environment;
4.* the writer is not a programmer and is therefore
not the architect of the DTD
5.* SGML limits the way things look

#3. is concerned, I believe, with constraints on the
actual content and framework (to use a less loaded term
than "structure") of what a writer writes.

These concerns articulate what many are feeling, and
why, in response, I solicited and edited the series of 8
articles that appeared in Technical Communication and
why I have spoken to several STC (Society for Technical
Communication) groups on the same subject. It seems
appropriate to condense some of my remarks and post them
here. This and additional material is being
incorporated into my book, a non-technical guide to
SGML, to be published by Van Nostrand Reinhold.

The argument that I am going to put forth here is that
structured word processing -- and SGML today *is*
structured word processing -- is the tool we have all
been looking for. If it doesn't seem like that yet, it
is because understanding is still low and the tools are
not mature. And, we, technical writers, better
understand it and start demanding what we need. The
workplace around us is changing again and this time it
is our tools --not the compositor's, the editor's, or
the account's -- that are at the center of the
transformation.

Keeping my remarks here brief, I will cite one small
example, put forward one general assertion, and conclude
with what I believe are the five characteristics of
working with a structured editor that have the most
impact on a writer's work.

One Small Example -- Things, not Strings

Often, when I write a technical document, I think of the
name of a tool or a command as a thing -- not so much a
string of words, but as one object. Why an object, not
a "string" of words? After all, any wp will insert a
string. But a string is not an object and a command,
menu item, or tool name is a thing, not a string.

The difference is this: a string, once deposited, is
just a bunch of words and no different from the same
words deposited in any other manner. That is, if my
tool's name is "weekly calendar", then I can write about
a specific "weekly calendar" and about the "weekly
calendar" tool and the computer has no means with which
to differentiate them. But, they are different and they
need to be -- for updates, changes, indices, hypertext
links, catalogs, and, not least of all, for format. If
my "weekly calendar" (tool name) is an entity, then I
am *not* constrained in my format, punctuation, or
choice of words or phrasing. I can write about the
feature, the tool, the menu choice, with total lack of
constraint (if this meets other requirements of usage)
because, having identified each reference as the correct
type of entity, the computer will keep track of which is
which in case one is changed, re-formatted, or re-
arranged. Without a structured editor, I had serious,
immediate constraints in my use of syntax and format
because I had to rely on these essentially secondary
characteristics to tell the computer which was a
description, which a reference, which a piece of jargon,
and so on.

The Big Deal is this: When you put your text in
containers and define objects within those containers --
as SGML does -- then the computer can know what you are
talking about. Before, it only saw an undifferentiated
text string. Now that you have told it what's what, you
can use the computer to manipulate these structures. I
don't know how this plays out for poets, but for tech
writers, this is simply a better way to do what we do.

One General Assertion Regarding Structural Versus Visual
Thinking

Do we think structurally or visually when we write?

It has even been posited that there has been a Natural
Selection among technical writers against those who
"think structured" in favor of those who think visually.
This is an interesting assertion, but I think, when you
look at the guts of the writing process, the dichotomy
is not such a deep, sharp divide as it is made out to
be. I question if there is a fundamental opposition
between those who think structure and those who think
pictures. The core of the matter is this: all non-
fiction writers -- and, with few exceptions, writers of
fiction as well -- think of structure. The real divide
is not between structured or unstructured composition,
but between structure expressed unambiguously in an
abstract language that the computer can understand or
expressed in sometimes imprecise, ambiguous visual clues
that a computer cannot always interpret.

What I call the WYSIWYG Wars -- SGML in a shoot out
against the pretty-picture editors -- is not so much a
question of structured versus visual thinking, but a
question of how is your structure expressed -- is it
visual or abstract? When posed in this light, the
difference between SGML editors and unstructured editors
becomes one of historical evolution and emphasis rather
than fundamental opposition. It is a question of *What
kind of structure are you comfortable working with?
What kind of structure do you need to carry over your
publication into multiple media?*

The writing process does change with a structured
editor, but far from giving something up in terms of
visual clues and feedback, I would make the case that it
is The Tool We Have Been Looking For All Along. SGML
enhances the native tendencies of the technical writer
to create structures and categories and connections,
regardless of whether or not the writer is accustomed
to working and thinking in a visual or an abstract mode.

The Five Characteristics Of A Structured Editor

WYSIWYG Wars

Let's look more closely at what the lack of WYSIWYG in
SGML means.

Actually, let's look at what it does not mean. It does
not mean that the screen of a writer using SGML looks
like a throwback to a primeval data terminal with no
buttons, icons, or graphic aids -- a picture which may
be mistakenly associated with the switch *to* WYSIWYG
for those who simultaneously went from character-based
to take-your-pick-GUI-word processor.

And, more significantly, it does not mean that the
screen of a writer using a structured SGML editor has no
visual clues indicating how things relate on the page.
This misconception is a throwback to the pre-adolescent
days of the SGML tools market. Today's tools, still in
their early teens, offer an abundance of on-screen
formatting features that allow the writer to approximate
final format, where this is desired.

Writers, technical writers most especially, have always
written structured documents. So, for the writer's
perspective, What You See Looks Like the Structure of
What You Write is far more significant than What You See
Is An Exact Replica of What Will Print. Of course, this
is just the writer's perspective. What of the case of
the compositor or where the writer is the compositor?
What of the case of the reviewer who does need a full
visual representation of structure -- one that matches
the final output?

These are important and interesting questions, but
notice that we have switched from discussing the writer
working as writer to the writer within a larger context
and to work flow questions in general. To confine the
discussion to writing, I will opt out with a note to see
my book under work flow -- which is where the rest of
the WYSIWYG discussion belongs.

Last note on WYSIWYG: There is no restriction on how a
document coded in SGML looks when formatted for print.


Controlled Tag Set

The controlled tag set enforces good corporate or
technical writing styles. SGML gives us the ability to
enforce rules that we didn't enforce before. It also
reminds us why we didn't.

Next to the desire to edit someone else's copy, there is
no greater desire on earth than to create a new style
tag that will make some relic fit the look of the
publication. Who among us has not, when nearing
deadline, found or created the first and only instance
of a bulleted-list-within-a-procedure? And who has not
engendered a new style tag to fit this instance?

How would this differ under SGML structured editing?
Where the tags are defined by the DTD and the document
must parse by the DTD, the author or editor simply
cannot invent a tag on the spot. In most SGML
implementations, the work of figuring out what to do
with the bulleted-list-within-a-procedure not only can,
but must be done up front. What, with unstructured
editors, manifests as a problem in typography at the end
of the process, is actually a problem in structural
definition, and as such, must be analyzed in the
document analysis that preceded the writing of the DTD.

Again, what started out as a writer's issue becomes a
work flow issue. Obviously, if the writer who resorted
to a bulleted-list-within-a-procedure had been using a
DTD-aware editor in the first place, the need for the
illegitimate formatting tag would never arise.

What, you say, you want to be able to invent new styles
like bulleted-list-within-a-procedure on the fly?
Nothing really prevents this, just be sure that if you
build in flexibility, you have flexibility throughout
the process. SGML forces you to articulate the decision-
making process and it pushes this process up front and
forces you to live by the rules that you set, until you
change those rules. If this is a constraint, it is no
greater a constraint than what you will find in any
competent text on technical writing.


Context Sensitive Markup

Context-sensitive markup is not only easy to describe,
it is easy to accept.

Context-sensitive markup means that only the tags
appropriate for where you are in the document show up on
the tag list. For example, if you are on the cover
page, you will not be able to select a chapter title --
it just won't show up on the list of available tags. If
you are working in a chapter, you won't be able to
select a publication title.

This has obvious benefits, not the least of which is the
sheer reduction in volume of available tags. When there
are only a dozen appropriate choices, why page-down
through the whole list of 200 style tags?

So, context-sensitive markup not only goes far to
enforce good usage, it just plain saves time.


Structural Validation (Parsing)

Structural validation is the formal vetting of the
document by the document type definition. Because this
is at the heart of so many of the ramifications of
writing with SGML, relatively little need be said of it
here. In trying to assess how your own personal writing
process may be affected by using a structured editor,
the only general comment I can make is to try to think
of it as an editor -- granted, it is an automated one,
one that brooks no argument -- but, the relationship is
not unlike the relationship of a writer to a copy editor
and an enforcer of corporate style.


Navigational Tools

Navigational tools, like context-sensitive markup, is a
feature of working in a structured environment that
should be cause for universal celebration. Consider the
added convenience now that your editing tool knows the
difference between footnotes and captions, between
instructions and descriptions. Then, imagine how much
easier it is to find instances of particular usage and
application.


Some Conclusions

We always created structure and format; we just threw
out the structure when we put our thoughts into
complete, grammatical sentences. We kept only the
format and format is a function of structure, not the
other way around. If we keep the structure, we can
continue to use it.

We must not confuse what SGML makes possible, but does
not require (two outputs from a single source;
separation of structure and format) from what it
requires: that you articulate structure, that you
articulate the relationship between structure and
format.

But, Its Not That Simple. The Tools Are Still Catching
Up

The problem is not how to adjust to thinking
structurally, but how to express structure in explicit
and unambiguous terms both in code and, where required,
in immediate visual terms. The tools have to keep
working to supply us with better on screen formatting
that is compatible with structured documents.

And There is Still No Free Lunch

Writing with SGML is different. Bob Glushko of Passage
Systems was right when he wrote of the implementation of
SGML at SGI: "More precise structural tagging requires
more work." This should not be a surprise -- greater
efficiency and flexibility, new products to offer, does
not mean a free lunch.

The red flags being raised over SGML are not wholly
without merit -- it is a critical juncture for technical
writers. If we throw up our hands at this and say that
we can't get involved, that structuring information is
not what our writing is about, we could limit our future
role. The most disturbing misconception -- on and off
the net -- about tech writers and SGML is the assumption
that tech writers are not doing and cannot do DTD design
and document analysis.

This is simply not a true reflection of how the
workplace is adapting to SGML. Technical writers and
editors are in the forefront of document analysis and
DTD design and implementation not only in individual
companies but in the collective work being done by the
OSF and the Davenport group.

Unless technical writers as a whole self-select out of
this, like the type shop hanging on to hot lead, I don't
know of any reason that we cannot make this the means by
which we become more essential to the whole product
development cycle.

Netiquette: I have mentioned my book not *only* as a
plug, but to indicate that the issues raised here are
really more complex than can be covered in a post-length
discussion.

I am eager for feedback. If any who see this post -- on
comp.text.sgml or on the tech writer's list -- are in
NYC, please come to the STC meeting on April 19th to
discuss these points further. Contact me for
date/place/time. Also, I would be happy to forward the
list I distributed at the STC/Lowell Interchange
conference on Eight Ways For A Technical Writer To
Become More Involved With SGML to any who wishes it.


Previous by Author: tech writing and SGML
Next by Author: SGML and Tech Writing
Previous by Thread: tech writing and SGML
Next by Thread: Re: Applying object-orie...


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


Sponsored Ads