SGML & TW responses (long post)

[Liora Alschuler <LIORA -at- DELPHI -dot- COM>]

B00000000000000
Following are some short replies to the
responses to my post on SGML and
technical writing.  I am very
appreciative of the feedback, I am only
sorry that I don't have more time to
devote to an on-going discussion.

Susan Fowler writes:

Assertion:  SGML is implemented "top-
down" by SGML designers.
Discussion:  The ISO standard was a
large, collaborative effort with much
diverse input and it continues as such.
SGML applications -- the various editors
and formatters -- are no more or less
top-down, as a group, than word
processors and non-structural desktop
publishers.  Ditto for SGML-based
production systems.

But, my guess is that the author of this
comment meant actual DTDs and SGML
databases.  Here, there is a great
potential for tech writer input.  The
best implementations cast a wide net
when collecting the group for document
analysis -- this group should and often
does include writers, editors and
production people from the "front lines"
-- not just supervisory personnel.
Prevailing wisdom is that bottom up
works real well -- but, there is nothing
inherent in the technology to say do it
one way or the other.  It's up to us.

Objection:  Susan writes:
  The SGML coding interferes with the
  intellectual work by making you focus
  again and again on the process of
  entering text--whenever you make a
  coding mistake, in other words, it
  beeps at you...

Discussion:  No one should work with a
system that is constantly beeping at
them.  Maybe  yours is trying to tell
you something.
Without knowing your system, I can
suggest three possible, generic
solutions:  1)  turn off interactive
parsing, or get an editor that lets you
turn it off, if yours won't; 2) Check
ways that your DTD can be improved, made
more flexible; 3) work-around, if 1) and
2) not feasible:  learn and anticipate
what is called for and supply it in
boiler-plate:  that is, if it demands a
list title, and you just want to throw
down some list items, just use a space-
filler "list-title" until you are ready
to do a title.

Must a writer writing to a DTD be more
aware of the explicit structural
guidelines set out for that publication
than a writer using the same guidelines,
but without a structured editor?
Ultimately, does the group as a whole
benefit if the writer is more aware of
structure as she/he writes?  Is this a
burden for the writer?  for the group?
I would like to hear discussion about
these questions.  I don't think one set
of answers fits all situations.


Question:  Why not use postscript?
Discussion:  It describes print
presentation, not structure.  Fine, if
all you  want to do is print.  This
point was addressed by another writer
in an earlier post and is discussed
extensively in the literature on SGML.

Complaint:  ..until tech writers wrest
the standards-making process away from
these bizarre SGML power trippers!
Discussion:  We are they.

Arthur Comings writes:
Assertion:  ...some people want to write
first and format later, but for
myself it's pointless to separate form
from content.... [my] mind-set that I'm
in when I write [is]: With all of the
tools at my
disposal, how do I best present this?

Discussion:  Yes.  Words are pictures,
after all.   But, I think there is a
range of presentation-while-writing
options.  The WYSIWYG we are used to is,
itself, an approximation of what is
printed, there being inevitable
differences in resolution between screen
and page.  And then, unless your task is
page composition, you are probably not
looking at a full page as you write.
(My page break is currently at mid-
screen, so what I see is not what will
print.)  And, for final, you may adjust
margins and leading and spacing.  So,
what I'm saying is that some visual
feedback is very helpful, and you can
set up an SGML editor to give you visual
feedback.  If what you need is an EXACT
replica of what will print, then you are
probably not stringing words together,
but doing page composition.  The other
examples you cite (...did this subhead
help me find the topic fast?...) are
equally operational without doing final
page layout as you go.

In a later post, Arthur Comings
continues:

Question:
  ...what's the big deal for me as a
  long-time user
  of Frame? A strict tag set? How much
  planning is REQUIRED here?
  I don't really buy the notion that
  you could plan a document so you'd
  never get in a place where you'd
  really feel you need a new tag.

Discussion:  Not just a strict tag set;
structure.  And planning is required.
Not always more than you did before, but
more of it is done up front.  I know
what you mean about new tags, but, we
all stop putting in tags at some point
(see your own point below).  There is
the possibility, with SGML, of putting a
tremendous amount of knowledge about
what is and should be in a publication
into the DTD.  And DTDs can be extended
and amended, just like software and
style sheets.

  I don't have 200 [tags] -- we've got
  probably fewer than 75 in ours (which
  I developed) and it's a pretty rich
  set. And I almost never need others.

75 is alot to page through.  Why not
look through 5, instead?

Question:  There were several queries
about my "things not strings" example.

  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.  ... a string, once
  deposited, is just a bunch of words
  and no different from the same words
  deposited in any other manner.  ...
  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.

Arthur Comings writes:  "...a feature or
a menu choice would usually have capital
letters in its title to differentiate it
from similar generic references..."

Discussion: Just my point.  Haven't you
ever been in the situation where you
relied on secondary characteristics
(format) and then the format of one or
the other type of thing changed?  (e.g.,
now all menu items are italics, tools
names are bold -- before, they were all
bold.  A writer or editor must find each
string and make a decision about which
usage is correct. )

If your text objects are, indeed,
objects, then you can manipulate format
however you want -- one way in print,
another onscreen, and you can have last
minute changes in format without loosing
the information the writer had in his or
her head when writing.  That is, when
you are writing, you know unequivocally
what something is -- a tool name, a
reference, a menu item -- why not make
that explicit and unambiguous as you
write?

I don't want to be constrained by the
need to make my format double as an
indication of structure.  It's fine to
let format tell the reader what the
structure is, but I want more knowledge.
Consider it the difference between the
way an ordinary user sees a building and
the way an architect sees a building.
The architect must keep in mind how the
final will look to the user, but the
architect needs plans and blueprints and
diagrams that show much that is
ulitmately hidden from the people who
use the building.  I want absolute
freedom to make my tool names look
however I want, not relying on format to
tell me what they are -- until I'm ready
to format each separate output (print,
online,...).

In fact, the final print format may have
these items all look alike, but the
writer may want more detailed visual
feedback while writing.  The writer may
want to see -- at a glance -- all tool
references within a procedure -- try
that if you are relying on final page
layout for your structural clues!

In a later post  Susan Fowler writes:
   SGML forces a particular structure
  on a  document
  (head1>head2>head3>etc.)...
Discussion:  Someone who didn't know
much about SGML might misunderstand
this.  SGML, first of all, is a standard
for describing structure.  But, the
structure applied to any document can be
as loose or tight as suits your purpose.
As Susan says, its up to us to put the
Emperor's clothes on straight, i.e.,
make sure the structure fits the body.

Anatole Wilson writes:
  ...it bothered me when she said that
  SGML makes us write in a way that
  computers can understand.
  I've never written for an audience of
  computers, and I think it's unlikely
  I will in the near future. (Ten years
  from now, however, I'd say all bets
  are off.)

Discussion:  Glad you noticed that.  I
do not like anthropomorphizing of
computers.  Hate it, actually.  I did
not intend to imply that the computer
has a *human* understanding of what we
write, but I see how it could be read
that way, and I will correct the
misinterpretation.

Instead, my point was that the computer
can compute -- handle in the way that
computers handle things -- and keep
track of the information the way it
tracks databases and spreadsheets.

Is this writing *for* the computer?  In
an absolute sense, yes, this constrains
expression.  But then, we never wrote
without constraint.

Look at the difference between
typography and calligraphy.  The
constraints of typography restrict
expression -- but, it's a good trade off
most, though not all, of the time.  The
constraints of typography -- straight,
regular lines, clearly defined
paragraphs, going from left to right (in
English), and so on -- are a subset of
the constraints of most SGML
implementations.  Most SGML
implementations add further definition.
For technical information, this is
proving to be a good trade off.  Fiction
and non-technical writing call for an
entirely different type of discussion.

Question:  How does SGML affect the
audience?

Discussion:  Why should the audience be
affected any more than they were by the
move to desktop publishing?  In that
case, the reader saw alot of crummy
design work as people who now had the
tools to do design started to believe
they were designers.  That was less the
fault of the tools than of poor
decisions on their use.  In this case,
the tools are ours.  What we do with
them becomes our product.  Let's do a
good job.

Bonnie Robinson writes:

  My point is that you have to be able
  to envision the way you want your
  document to work in order to create a
  DTD (if this is what you are doing),
  or to tag and alter the material you
  are working with. Well, maybe you
  don't HAVE to , but it certainly
  helps.

Discussion:  I'm not sure I know what
you are trying to say here, but I can
comment that SGML implementations do not
work for those who make up their
structure as they go.  At least, not
yet.  I envision an application that
will help you do that, but for now, SGML
implementations require that the
structure be thought-out ahead.  There
are getting to be some cool tools --
work group tools -- for doing this.


Objection:  Several people wrote about
SGML and the limits on presentation.

Discussion:  SGML does not limit
presentation.  Structure in SGML, then
format and present using any tool you
want.  See my article in the June
Publish on using Quark as the
composition engine for SGML files.

Regarding the quote from van Herwijnen:
I missed the post with the
quote/misquote.

Len Olszewski says the same thing as I
do regarding limits on presentation,
although he refers to FOSIs as the
vehicle for formatting.  I don't know
many outside the DoD world using FOSIs -
- and I have a different use for the
initials.  There is really no need to go
to a FOSI, the formalism and rules
checking for format has a limited use.
I prefer (as a default model) *any*
composition engine that fits the overall
production environment.

Susan Fowler writes that Frame and
Interleaf can filter documents in and
out, even annotate and export them in
their native format.  So, why, she asks,
struggle with SGML to achieve cross-
platform compatibility?

Discussion:  I agree.  Cross-platform
compatibility is not a sufficient
argument for SGML.  As long as you can
control the to and from of your
information and as long as one
source/destination does not get too out
of sync with the others, filters can
work, although to keep them able to
handle 100% of the markup, there will be
maintenance and controls and limits on
templates and styles.

But, many people cannot constrain the
source/destination format of their
information.  And anyway, SGML does more
than that.  For many who use it, the
value of platform independence is
superseded by the value of vendor
independence.

And while some high-end composition
engines, like Interleaf, give you
limited flexibility in terms of output
(e.g., WorldView), they can't match the
richness of SGML online viewers using a
robust DTD.  Where a high-end
proprietary formatter lets you do some
things with structure, it is acting
structure-aware, which may meet all your
needs.  But then, it is just this type
of encoding that would be hellish to
translate freely between proprietary
solutions.  And the ability to annotate
is fine, but what of the ability to
edit?

SGML-based production is not appropriate
for all situations and will never be.
But, knowing very little about EJV,
except what the initials stand for, and
knowing that the SEC is getting quite
serious about SGML-based electronic
filing (EDGAR) and hearing through the
grapevine that EDGAR is only the tip of
the iceberg in terms of financial
applications for SGML, I would be very
surprised if you can make a good case to
drop it.


I look forward to more SGML posts,
although I will be out of radio range
for a few days.

I have sent out the of Ten (Was Eight)
Ways for Techwriters to Get Involved
with SGML.  If I missed anyone, or
others want it, please let me know.

Regards,

Liora





        Liora Alschuler
      /
  /\/    The Word Electric

        Route 5, POB 177
        East Thetford, VT
        05043
        802/785-2623
        liora -at- delphi -dot- com