Re: tech writing and SGML

Subject: Re: tech writing and SGML
From: Debra Carnegie <deb -at- SYMBOLOGIC -dot- COM>
Date: Tue, 12 Apr 1994 16:36:00 P

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


Previous by Author: Applying object-oriented concepts to documentation
Next by Author: Re: SGML Forum in New York
Previous by Thread: Re: Gendered Communi...
Next by Thread: tech writing and SGML


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


Sponsored Ads