TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: XML as Help Format From:Megan Golding <mgolding -at- secureworks -dot- net> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:18 Oct 2001 09:53:33 -0400
On Thu, 2001-10-18 at 07:34, Robert_Johnson -at- percussion -dot- com wrote:
> The developers in this company want to use XML as theHelp format. I
> have
> not heard anything about using XML as a Help format, and a search of the
> techwr-l archives and a couple of Web searches have turned up nothing.
> I
> figure that if anyone was doing any work on using XML in this manner, we
> would have heard something, either on the list or from one of the HAT
> develoeprs.
Robert, et al:
I'm using DocBook SGML (and could as easily be using XML) for a
home-grown help system with our web UI. We have help buttons on web
pages that use javascript to generate a pop-up window with the help
topic.
To create "help files" (really a series of HTML docs), I perform the
following general procedure:
1. Write content using a text editor. I place all DocBook markup in the
documents by hand.
2. Convert DocBook files to HTML using "jade", an SGML processing tool.
For XML, similar tools exist and go by names such as Saxon and Xalan.
3. Communicate HTML file names (hooks) to the developers so the help is
context sensitive.
I've worked with RoboHelp before and found the general procedure to be
very similar. My only problem is that DocBook has a steep learning
curve. Not a problem for me, per se, but its a problem for getting
others integrated into the help writing process. The DocBook->HTML
solution is more like development than like writing. But, the more I
think about it, I had these problems with RoboHelp...
Markup in DocBook is very rich. I can mark a word as <command> for a
command line term, write a <procedure> when needed, and give cross
references (<xref>) when the need arises.
The only thing lacking from DocBook at this point for writing help
systems is a paradigm for help topics. DocBook documents are written
with a <section> within a <chapter> within a <book>...etc. The
topic-based nature of help doesn't shoehorn in very clearly to DocBook's
current state. I wrote each help topic as a <section> within a
<chapter>. When I think about the topics, I would think it'd make more
sense to tag a help topic as <topic>.
Interestingly, on the DocBook list (docbook -at- lists -dot- oasis-open -dot- org), there
is a conversation going on right now about adding help topic tags to the
DTD. The thread is archived here: http://lists.oasis-open.org/archives/docbook/200110/msg00082.html.
To learn more about using DocBook (available in both XML and SGML
versions) for help authoring, I'd suggest you check out the docbook and
docbook-apps mailing lists (subscription and archive info at http://lists.oasis-open.org/archives/). Also, many Open Source
development projects are using DocBook for their help systems. Check out
GNOME Documentation Project (http://developer.gnome.org/projects/gdp/).
John Fleck at GNOME is working on a help rendering system with XML at
its core.
The DocBook approach does have a big learning curve (like learning HTML
plus learning all the document conversion/processing tools that are
somewhat tricky). If you want to stick with the Windows/GUI route, I ran
a search and noticed Webworks has XML support: http://www.webworks.com/company/pr050800.asp.
Good luck!
Meg
--
Megan Golding (mgolding -at- secureworks -dot- net)
SecureWorks, Inc.
Don't worry about the world coming to an end today.
It's already tomorrow in Australia.
-- Charles M. Schulz
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
