TECHWR-L: XML & the future of tech writing (topic from last week) LONG

["Chris Knight" <cknight -at- attcanada -dot- ca>]

I want to reply to some of the points raised to my message about XML and the
future of tech writing.
I've been away a few days, and a bit lazy about checking my mail.

To my comment
> But eventually, much of tech comms will be using XML.
> Count on it.
Andrew Plato <intrepid_es -at- yahoo -dot- com> said on Fri, 19 Oct 2001:
> No, I wouldn't count on it. I would count on a lot of organizations
> sticking with existing technologies like Word and Frame because they are
> reliable, well-know, and inexpensive (in comparison to adopting new
> stuff). You can't swing a bad style guide without hitting a tech writer
> that knows these tools.

It is precisely to users of these tools that I am talking. Mr. Plato seems
to think I am advocating some nerdy "advanced" tool.; not so. I am talking
about working tech writers working with the available tools, but realizing
that there are strong forces at work pushing us toward tools that read and
write XML. I believe that as users of these tools we should in turn push the
tool vendors (especially Microsoft and Adobe) toward achieving this end.

Let me be more specific about the "strong forces at work pushing us toward
tools that read and write XML":
I am talking about organizations which produce large amounts of documents,
and consequently employ large numbers of us to produce those documents. Such
organizations want both increased productivity AND increased flexibility out
of publications groups, and they want to do it while increasing the control
they have over the content of those publications. (I include here any form
of delivery--print, help, online). Thus the mantra of "single sourcing".
More on that later.

Andrew Plato also said:
> They just want the information to be correct. Thus, there isn't much
financial incentive to
> adopt new technologies for a service that can be completed with capability
> using existing technologies.

This may be true in some quarters, but I submit that my description applies
more and more to large producers of documents. Eventually, the bean counters
will mandate it as far as they can reach.

As to the rest of Mr. Plato's rant alleging that this is some sort of fringe
technology, many companies and organizations are adopting XML standards,
i.e. creating DTDs (Document Type Definitions). But more fundamentally, I
was predicting how things will go, which is always a risky task. As to Mr.
Plato's implication that I am emotionally attached to some arcane fad, I
consider that an uncalled-for argumentum ad hominem, and quite silly.

To my comment:
> XML will allow us to store information in an appropriately structured way,
> then search, retrieve, and present, to both humans and computer programs,
> that information.
Rick Kirkham <rkirkham -at- seagullscientific -dot- com>, on Mon, 22 Oct 2001 takes
issue:
> This is misleading. XML is only a family of markup languages. *It* won't
> "search, retrieve, and present". Only applications that can parse and
> process XML will do these things.
Mr. Kirkham is correct. I am aware that applications are required; that is
what I was talking about when referring to word-processing tools: I'm
calling for us to push the tool vendors to make this easier for us, not
claiming that is already available to us. (Although thanks to Katie Kearns
for suggesting that XMetaL Pro by softquad was worth a look.)

To my comment:
> This in turn will not happen unless writers (users in general) have
WYSIWYG
> tools. As far as I know, one cannot NOW use such as Word or Frame to
create,
> edit, print, documents which in fact use XML (and associated DTDs and XSL
> stylesheets) as their file format. Conversion to/from XML, yes, but not
> work with XML files. Am I right?
Mr. Kirkham said:
> I don't think you are right. XML is not a file format, like ASCII, or the
> proprietary formats of Word or Frame, so it is not really coherent to even
> ask the question whether those tools can work with files that "use XML as
> their file format". ... Hence, to speak of WYSIWYG tools for XML doesn't
> really make any sense either.

Mr. Kirkham is correct about file format, but misses the point. He seems to
be incapable of imagining that word-processing tools could use XML (plus the
DTD and the XSL stylesheet---all ASCII files) to represent what would up
till now be stored in proprietary file formats. That is precisely what I am
imagining, and what I predict will be available (soon, I hope).

Mr. Kirkham also said:
> By the way, you CAN create XML documents in Word and Frame. Just save them
> as plain text. This does not involve conversion to/from XML. It is
> conversion to/from ASCII, but the files are always XML.

As far as I know, this is largely untrue. According to Jason
Willebeek-LeMair" <jlemair -at- cisco -dot- com>, there is available a product "called
WorX. It is an XML editor add-on for Word" (thanks Jason--I'll check that
out); other than that, Word cannot do it. FrameMaker can (with an very
expensive version) read/write SGML files, which is close, but not quite XML.
Quadralay may convert to/from XML, but that's not what I'm talking about. As
to just saving all your carefully-formatted document as plain text, that is
just silly.

What I'm talking about is being able to use your existing knowledge of Word
or Frame to create and edit documents, but that these be stored COMPLETELY
in XML (and DTD and XSL), not .doc or .fm files.
Hence my question:
> Has anyone found a word-processing feature that *cannot* be rendered in
XML?
By "word-processing feature", I mean things such as automatic TOC
generation, named text ranges (what Word calls "bookmarked text"), text
variables, index references and automatically updated indexes etc. etc. I am
still interested in this--anyone have experience in this regard? I have a
friend who has been contracted to write a book for a major publisher, and is
thinking of submitting the "manuscript" to the publisher exactly as I have
been describing. They already have a DTD, but I don't think they publish
directly "in XML": most likely they use publishing software that will
convert the XML and apply a template rather than an XSL stylesheet. I intend
to see what's possible myself as soon as a suitable project comes along.
I'll keep y'all posted.

Katie Kearns <kkearns -at- cisco -dot- com>, on Tue, 23 Oct 2001 got the point:
> I think the whole point is just that a different sort of interaction
between programs
> is made possible using XML -- and that's true. The key phrase is
"appropriately structured".
> Other formats are not appropriately structured.

Let me add some more to fire the imagination (especially for those who think
that this is just another tool or format).
It won't just be word processing tools that will use XML as document
storage: most XML in fact will actually be created and maintained by
database systems. Work is ongoing to interface XML with SQL (Structured
Query Language); one implementation wending its way through the standards
mill is called XQL.
This is how "single sourcing" will be implemented: we'll store the document
*content* in one place, as a database implemented in XML, and store document
*structure* elsewhere (also in XML). Document *format* will be stored in the
stylesheet.
Using this approach, we could define a "PrintedGuide.xml" and a
"HelpSystem.xml", both of which in turn reference the database containing
the specific product information, and probably other databases containing
common company elements--the sort of thing we have "boiler-plate" files for
now. All facts--all entities--are stored in one place.

Assuming I'm correct that this will happen in the context of WYSIWYG tools,
what will all this mean for writers?--after all who cares what the file
format is as long as it does the job, right?
Well, if a tool is going to use XML to store the document, the document must
at all times be formally correct XML: each element will have to be properly
tagged, or it won't display (or print). The tool must take care of this, so
it simply won't let you do anything that would generate improper XML: you
wouldn't be able to just type in text, you'd have to specify what sort of
structure the text has first. You wouldn't be able to type something and
then decide it was step in a procedure. You wouldn't be able to create a
step in a procedure if you hadn't already created the procedure. Everything
will be an instance of a type of structure, and every type of structure will
have to be defined in the DTD. All formatting is defined in the stylesheet
(which like the DTD will probably be accessible only to editors, not
writers). There will be NO direct formatting; it will be impossible to do.
Formats will always be relative to the structural element that contains the
formatted text. Etc. etc.
As a result, in some ways writers' tasks will become easier. However, anyone
who has difficulty separating content from structure and format will have to
relearn how they write. This could be a major change for many of us. In my
judgment, it will make us better writers.
Also, we may eventually see specialization: some writers mostly developing
content, others developing the structures by which the content is delivered
to users.

I'm just engaging in (informed, I think) crystal ball gazing folks. Will
this happen all at once? No. Will *everybody* decide to use XML? Certainly
not--as I said, this will probably only be adopted in large or particularly
security-conscious environments. Even in such organizations, casual
documents which we don't expect will ever be seen, edited, searched, or
printed again, need not be created or stored as XML. But I will predict that
XML, rather than any proprietary format, will become widely used as the
preferred method of storing large amounts of information in single-source
modules, and that this will affect many tech writers' working environment.

_____________________________________
Christopher Knight, Technical Communicator
http://members.attcanada.ca/~cknight/
E-mail: cknight -at- attcanada -dot- ca
Phone: (604) 877-0074


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.  
For details and online registration, visit http://ieeepcs.org/2001

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.