Re: tech writing and SGML

[Debra Carnegie <deb -at- SYMBOLOGIC -dot- COM>]

(apologies for posting this to the entire list - there was no specific email
address provided)

I would be very interested in receiving this list.

>....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.

Thank you--

Debra Carnegie
Symbologic Corporation
deb -at- symbologic -dot- com

 ----------
>From: TECHWR-L
>To: Multiple recipients of list TECHWR-L
>Subject: tech writing and SGML
>Date: Tuesday, April 12, 1994 1:08PM

>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.