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

[Deborah Ray <debray -at- RAYCOMM -dot- COM>]

Excellent question--and thanks for helping bring focus
to this discussion. I think what's key in your
posting is the aspect of "how will tech writers
use XML," which is the question that got this
whole discussion started.

<Note to our techier experts in this discussion, I vote
that we don't quibble over semantics and work together
to answer this. Thanks.>

You said:
>The XML experts on this list are very persuasive. So much so, that I find
>myself agreeing with opposing views according to the last post I have read.
>This is partly because I do not fully understand the process. I know XML
>promises to be a really important development to technical writers and I
>think it might be helpful if the experts could let us in on the intricacies
>of XML using language week can all understand.

I can see where it'd be easy to go back and forth on this topic.
Participants in this discussion have presented tons of information,
not to mention that XML has the potential for so many different
uses that are neither straightforward nor easy to visualize.
>
>As a start, tell me if I've got this right. Suppose you wanted to create an
>XML document, send it to somebody else, and be sure they would be able to
>see it in the way you wanted them to see it. This is the procedure you would
>follow:
>
>1. Create a DTD containing some rules defined by XML.
>2. Create a tagging language conforming to the DTD.
>3. Create an application program that will convert text formatted according
>to the tagging language into a form suitable for viewing it on a particular
>platform under a particular operating system.
>4. Create the document.
>5. Format it according to the tagging language.
>6. Send the document to someone else.
>7. Also send the DTD.
>8. Also send the application program.
>9. The recipient passes the document through an XML parser to check
>compliance with your DTD.
>10. The recipient passes your document through your application program.
>11. The recipients views your document.

Dave, the fact that you put these steps together is
(further) proof to me that XML is an ideal tool for tech writers.
As I said in my original posting, XML lets us apply skills that
we've already mastered. You've effectively taken scattered
information, assimilated it, and put structure to it--
which is, in part, EXACTLY what developing XML applications requires.

Anyway, as for your steps, you're close. In fact, the steps listed
are a bit more complicated than it needs to be. Here's a likely
scenario of how tech writers (or other XML authors) might develop
XML documents <note that I say "likely," not "always">:

1. Create a DTD, which specifies the structure, rules, tags, and
   attributes allowed/required in the XML document.

2. Optionally, create a style sheet, which eventually will specify
   formatting for the XML document. You could have multiple style
   sheets for different purposes and use any or all of them with
   the DTD from Step 1.

Think of these first two steps as being similar to setting up
a template in Word or Frame. They set up a standard format/structure
that you reuse as needed.

3. Create the XML document using the DTD specifications. In addition
   content, you also specify how the XML document connects to the DTD
   and style sheet. You could embed them in the XML document or link
   to them, either on the Web or as another file you'd send with the
   XML document.

Think of this step as being similar to providing content to pour into
an existing template. Connecting the XML document to the DTD and style
sheet uses similar principles used in embedding and linking in HTML.
(Linking in this context means connecting the documents, not creating
a "click here.")

4. (For your example) Send the document to your coworker or whoever,
   including the DTD and/or style sheet as needed.

With this process, your coworker would be able to open the XML
document with her/his XML tools and be able to view the document
complete with the style sheet and DTD applied. Eventually, the XML
tool could well be Navigator 5.0 or IE 5.0, but until then this would
assume that the coworker has access to a specialized XML parser.

The real value to this process is that, once your coworker has access
to XML tools and has the DTD available, then he/she could easily
create compatible, structurally identical documents--without
having to reinvent the wheel.

Again, thanks for asking this specific question and for
focusing the discussion a bit. Hope this helps.

Deborah


**************************************************************
* Deborah S. Ray, debray -at- raycomm -dot- com, http://www.raycomm.com/
* co-author _Mastering HTML 4.0_, _HTML 4 for Dummies Quick
  Reference_, _The AltaVista Search Revolution_, and others.
* RayComm, Inc., currently accepting contract inquiries.