Re: XML & Technical Writers...(long)

["Eric J. Ray" <ejray -at- RAYCOMM -dot- COM>]

<VERY LONG--sorry!)

At 10:36 AM 4/15/98 -0400, Mark Baker wrote:
...
>There have been standard DTDs for documentation for years: SGML DTDs. Most
>major industries have them. Few companies actually use them. But remember
>that a DTD defines a language. HTML has an SGML DTD, but we don't say
>someone is using SGML when they author in HTML. If we did create a single
>DTD for documentation, it would define a specific language (let's call it
>TDML for Technical Documentation Markup Language). Now when we use TDML we
>are not using XML anymore, we are using TDML. If people write TDML tools,
>they will be TDML tools, just as todays HTML tools are HTML tools.
>Individuals will not be able to extend TDML without writing their own
>processing tools, any more than people today can extend HTML without writing
>their own tools. Tagging languages can be usefully extended by those who
>write the tools that process them, and not by anybody else. It you want the
>freedom to design your own language, you must accept the responsibility for
>creating your own processing applications.

But this completely misses the point--and the functionality--of XML.
None of us would advocate creating a TDML, because by the very
nature of our profession, our needs tend to be unique to what
we're doing and unique to our audience.

The fact is, XML lends itself to development of new tagging languages
to meet specific needs, and the few tools currently available support
this flexibility. Currently available (crude, but functional) XML
editing tools allow users to specify the DTD they want to use,
and that DTD could be either a common standard OR a DTD that meets
specific unique needs. Additionally, the announcement of full XML
support in Netscape Communicator 5 as well as the next version
of Internet Explorer, lends some additional credibility to the
XML-as-a-generic-solution model, rather than to your XML-as-another-
expensive-SGML-product version.

>Perhaps, but none of these things will happen unless people in the
>industries concerned write processing applications to do all these wonderful
>things.

Mark, perhaps this is the time to point out that (by my understanding)
your company provides tools to do many of these things, and to do so based
on any arbitrary DTD.
See http://www.omnimark.com/magazine/tips/htmldown.html for
a neat example of converting arbitrary XML to HTML code. This tool,
among others, makes it feasible *right now* to store data as XML
and to provide it to users as HTML. Why store data as XML--as opposed
to just storing it as HTML? Because keeping information in some
XML flavor allows you to preserve meta-information about the data,
as shown below.

>Okay, here's an XML DTD:
>A DTD tells you what tags there are and what order they are allowed to be
>in. Nothing else.

Actually, it tells you what tags there are, what must/may/can/may not
be there, and that's enough. Let's try another DTD example:

<!doctype FAQ [
<!element DIALOG ( QUESTION, ANSWER)+>
<!element QUESTION (#PCDATA)>
<!element ANSWER (#PCDATA)>
]>

A document conforming to this DTD might include this code:

<FAQ>
<DIALOG>
<QUESTION>What's the importance of XML?</QUESTION>
<ANSWER>It provides a new set of valuable tools for information
        processing.</ANSWER>
<QUESTION>Why does it matter to technical communicators?</QUESTION>
<ANSWER>In brief, it empowers them and helps keep, store, and use
        information in context.</ANSWER>
</DIALOG>
</FAQ>

Now in this sample, you have both QUESTION and ANSWER elements,
which must occur in that order. Identifying an element as a
question as shown here, rather than as bold and italic as it
might be presented in an HTML document, makes it possible
(given scripting or presentation tools) to manipulate, present,
abstract, or reformat the document based on the content.

At a broader level, using a common DTD for developing information
makes sharing or exchanging information more feasible and
easily accomplished. If RayComm publishes an XML DTD for
topic summaries, and people who contribute summaries use the
DTD, 75% of Deb's maintenance work can be automatically
eliminated. This is a real-right-now application.

>any case, DTDs describe tagging languages and they accompany the tagged
>document, not the application. The whole point of an SGML or XML compliant
>application is that it does not have a DTD in it, but that it can read and
>understand any DTD fed to it.

Exactly! That's why you provide a DTD that describes your data, and
the data, and a style sheet to format it. And that's something that
I think we'll be doing and viewing in Netscape Communicator before
the end of this year.

>>Mark wrote:
>>...in itself, XML does not eliminate the
>>> proliferation of formats, it contributes to it. (Everybody and his
>>> dog can now create their own tagging language.)
>>>
>>Then why are chemists now able to read and interpret and share
>>information based on the DTD for chemistry (and there is one for math
>>and one for pharmaceuticals) with the aid of an XML parser?
>
>Because someone wrote processing tools for the markup languages they
>created. That's the point: an industry with specific needs creates a tagging
>language and a set of processing applications that meet those needs. The
>point of XML and SGML is that they provide a standard way of describing the
>grammar of a tagging language. This means that the language and the
>processing applications can be built using higher level tools that parse
>SGML or XML. Building them is very much easier than it would be without
>these standards, and the tools based on them, but they must still be built.

But this is putting the cart before the horse. If one of our clients
called today and said that they wanted us to develop a documentation
set for a vaguely Internet-related product with a five year life cycle
and a strong need for information reuse and online/Web presentation,
we'd probably push strongly for XML as an information development
medium.  The basic tools for information development are available
now, they maintain a higher level of information about the content
than, say, HTML does, and all signs point to broad reuse and repurposing
potential. At the worst, a valid XML document can be converted to
ANYTHING, including Word or Frame, with some fairly trivial
scripts. And, as more and better tools become available, more complex
and flexible processing is possible.

Just as words contained in a good Frame document are more valuable
to technical communicators than words in an ASCII text file (because
the heading tags, body tags, caption tags, etc. provide information
about the words that make it easier to understand and reuse them),
words contained in a good XML-derived markup language are more
valuable than words contained in HTML (because the significance
of words enclosed in <ANSWER> tags is clear, while the significance
of words in <B><I> or <H3> tags is not).

>I am not unenthusiastic. In fact, I am very enthusiastic. After all, I have
>chosen to work for the company that makes the best XML and SGML programming
>tool you can buy (OmniMark). I am an active proponent of content management
>systems which use XML/SGML as a vital component. I am simply alarmed by the
>general failure to appreciate that the point of XML is that it allows you to
>create custom information processing application very much more easily than
>if there were no standard. It is custom processing applications that do the
>real and exciting work. That is where people's enthusiasm and attention
>ought to be focused.

Perhaps we're saying the same thing from different sides (and perhaps
your familiarity with processing applications gives you a different
perspective), but where MY enthusiasm and attention is focused is
on a potentially very powerful tool to deliver information to my readers,
AND to keep that information in a format that lends itself to
reuse AND to be able to process or develop that information according
to rules that I specify, based on the unique needs of the client
and audience.

Given your employer (and some nice white papers on the site
with your name on them), I can see your emphasis on processing
applications--but the real significance of XML is information
focused, not processor focused.

Processing application? That's a waiting game. With XML, I can
specify the rules (my DTD), the content (my document), the
appearance (my stylesheet), and I don't doubt that tools will appear
to meet my needs--I don't know for sure, but rumor has it that
Frame will shortly support XML, and if I could use an XML-derived
DTD in lieu of a Frame template, I'd have the best of most worlds.

To return to your original point, a TDML (technical documentation
markup language) doesn't serve anyone's purposes--using that
would be like using a generic and uncustomized Frame document
template for a specific client. However, it could be a great jumping
off point for custom DTDs to meet specific needs--and with the
added benefit of being software and platform independent.  And
THAT'S significant.

Would welcome other comments and opinions on this--either
on or off list.

Eric



*********************************************************
* Eric J. Ray, ejray -at- raycomm -dot- com, http://www.raycomm.com/
* TECHWR-L Listowner, co-author _Mastering HTML 4.0_
*   _HTML 4 for Dummies Quick Reference_, and others.
* RayComm, Inc., currently accepting contract inquiries.