Structured Documentation and Us

[Fred M Jacobson <fred -at- BOOLE -dot- COM>]

Greetings-

The thread called "Technical Writers vs. Technical Communicators" is
discussing whether the role of the technical communicator is diminished
by the requirements of SGML or a similar system.  I want to discuss
structure in documents and how we handle it as technical communicators.

All writing in our usual experience has structure: words, sentences,
paragraphs, salutations, and the like.  The purpose and meaning of the
structure in everyday writing is governed by convention that most
literate people understand.  Technical communication often has more
elaborate structure.  It is conventional now for technical documents
to begin with a section called "How to Use This Book" to explain the
structure.  Many of us must produce documentation that conforms to a
standard structure defined by others.

Many tools we use allow us to express the structure of documentation.
I don't know about the original runoff program, but UNIX nroff, a
markup language that is about 20 years old, can do this.  Instead of
setting certain text attributes before a second-level heading (say) and
resetting them after, you can define an nroff macro and use it to label
the heading as what it is.  Then, later, you can change the treatment
of such headings by changing only the macro definition.  (This is "late
binding" of text attributes; the attributes are fixed or bound only
when the macro is evaluated at formatting time.)  You can do the same
thing with larger documentation elements (procedure, example), but I
don't think this is dome in the most commonly-used nroff macro packages.

The more advanced WYSIWYG document preparation packages can do the same
thing.  In Word for Windows or FrameMaker, I can create a style or format
for second-level heading, procedure, or example.  If I decide to format
these elements differently later, I can just change the style.  (In
FrameMaker, at least, it is easy to import a complete set of paragraph
formats and completely change the presentation of a document.)

But for this method to work, I must stick to a set list of elements.  If
I decide that I need a new kind of paragraph in the middle of a document,
I can either violate or modify the document structure.  A complete
structure can get pretty big: I may need a multi-paragraph note to a
third-level procedure step.  Even if the structure is adequate, I may
find it constraining.  Ah, but that's the point!  The structure is an
additional constraint on me as a technical communicator.  My job is to
express concepts, facts, procedures, and the like as effectively as I can
given certain constraints.  Any predefined document structure, whether
it is my company style guide or DOD-mandated SGML tags is part of my job.
If the structure makes it impossible for me to communicate effectively,
I need to try to change it, but I think I am still a technical
communicator even if my responsibilities do not include defining the
structure and final presentation of what I create.

If this additional constraint bothers you, if you want to be left alone
to create and do things however you want, read up on what happened to
computer programming when discipline and structure became more important
and personal independence was reduced.  This revolution is still going
on, and the results are not yet in, but there still seems to be room for
competent and creative programmers.

We always hope, of course, that the results of twisting our work methods
and product to fit a standard will be obvious and overwhelming benefits.

-Fred

--
INTERNET: fred -at- boole -dot- com           PHONE: (408) 524-3292  FAX: (408) 730-0558
USPS: Fred Jacobson / Boole & Babbage / 510 Oakmead Pkwy / Sunnyvale CA 94086