RE: Creating help file in XML.

Subject: RE: Creating help file in XML.
From: Rick Kirkham <rkirkham -at- seagullscientific -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 5 Mar 2002 10:38:17 -0800

Robert Rinehart wrote:

> I was told to create a help file in XML. There will also need
> to be a printable manual. I am to create these in Word 2000.
> I have never used XML before. I am told I can build the help file
> (procedural) first, then create the printable manual from it.
> Does anyone here know of an online tutorial or book that will allow me to
> learn how to create this XML help file in Word 2000?

Whoa! I don't think your superiors have any idea what they are asking. This
a major, major, major project they are assigning to someone who's never used
XML before, and you should anticipate weeks of research before you type a
single word. Producing documentation is a specialty within techwriting that
is far rarer, and far more difficult, than specializing in a tool like
Framemaker, or even a simple markup language like HTML. When you have
finished with what they are asking for, be sure they double your salary. (If
they don't, you'll get double from someone else; just add that successful
XML experience to your resume!)

XML is not a file format: You cannot "Save As" XML from MS Word. XML is a
family of markup languages. The file format of an XML document is plain
ASCII text. You could, in principle, create an XML document in Word (and
save as plain text, not as a *.doc or *.rtf file). But Word would be a very
poor choice because you would have to type every single markup tag by hand.
There are XML editors that enable you to add your tags as fast as you apply
styles in Word or Framemaker. (Lookup "XML editor" in your favorite web
search engine.)

Word 2000 *is* an HTML editor. Are you sure your superiors didn't mean HTML
instead of XML? What you wrote would make a hell-of-a-lot more sense if I
plug "HTML" in place of your "XML".

You will need to pick which XML language you are going to use fairly early
in your research process. DocBook is probably the best known XML language
for producing documentation. But there are others.

You will also need to create an XSLT document that translates the XML tags
into the formatting language of the format in which you will be printing you
manuals (e.g., PDF).

Finally, you will need an XML parser/processor (which may or may not be
included with the XML editor) that will actually transform the source XML
into the final output format (using the XSLT).

By the way, I skimmed a few paragraphs of the article Kevin mentioned, and I
want to warn you that I saw some mistakes in it. (The author says DTD stands
for Data Type Definition, it actually stands for Document Type Definition.
The author uses XSL when he should be using XSLT.)

Now's a great time to buy RoboHelp! You'll get SnagIt screen capture
software and a $200 onsite training voucher FREE when you buy RoboHelp
Office or RoboHelp Enterprise. Hurry, this offer expires February 28, 2002.

Have you looked at the new content on TECHWR-L lately?
See and check it out.

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 for more resources and info.

Previous by Author: Depression, Harrassment, etc. (WAS: RE: What a predicament!)
Next by Author: Worst technical manuals... humour...
Previous by Thread: RE: Creating help file in XML.
Next by Thread: Depression, Harrassment, etc. (WAS: RE: What a predicament!)

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

Sponsored Ads