Re: XML-based Help Authoring tools for customized help

Subject: Re: XML-based Help Authoring tools for customized help
From: "Mark Baker" <listsub -at- analecta -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 18 Dec 2003 11:52:28 -0500



Sean Wheller wrote:

[a lucid explanation of the Docbook extension process]

At the risk of igniting another fire fight, let me suggest an alternative
strategy and the reason that I prefer it.

Let's call Sean's approach the "extend strategy". My approach is the
"prepend strategy".

The usual reason for creating an extension to a markup language is to
capture additional data semantics, to improve validation, or to provide
additional guidance to authors. Another reason might be to enable some kind
of synthesis or formatting effect not available with the base language.

In the case that the purpose is to capture additional semantics, my strategy
would be to create a markup language from scratch specifically to capture
those semantics. I would keep this language as small as possible, so that it
is easy to learn. I would draw common elements from whatever language I
though my writers were most likely to be familiar with. I would keep it as
tight as possible so that it is easy to validate and easy to transform.

I would then write a transformation routine to transform documents written
in this language into standard Docbook. From there I would use the standard
Docbook tool set, or one of the alternative tool sets, unmodified, to
publish my content.

My reasons for preferring this strategy are as follows.

1. My part of the publishing chain belongs entirely to me. I am not
interfacing with anybody else's software (except by sending it messages in
Docbook format). I find this easier to manage.

2. Since my part of the publishing chain belongs entirely to me, I am not
tied to DocBook. I have the option to plug my system into any other
publishing chains simply by transforming my data into the appropriate
format.

3. My DTD is my DTD. I don't have to worry about integrating with the
Docbook DTD. In fact, I can use any schema language I like. I can even use a
different kind of markup language altogether, if circumstances dictate.

4. I can make my tagging language easier to use by aiming it as closely as
possible at the particular skills and knowledge of my writers. In some cases
it is possible to get the training time down to twenty minutes using this
approach.

5. By making my tagging language tight and topical I can prevent many errors
and catch many other right at the start of the process. The earlier an error
is caught, the less it costs.

6. It is a layered approach. Clear separation between the layers makes it
easier to adapt to changes in any of the layers. Modifying an existing
layer, even through a defined extension mechanism, always has some potential
to create difficulties with future compatibility.

If your reasons for wanting to extend Docbook are that you actually want to
modify the tool chain to produce some effect that it does not currently
support, then this strategy alone will not work. But there are two things to
note here:

1. Using this strategy, I am independent of any one tool chain and I can
look for any tool chain that does support the effect I want and target it
instead.

2. Even if you do modify the DocBook tool chain, you can still use a prepend
strategy for your data capture. This can simplify the modifications you need
to do to Docbook, and it still gives you many of the advantages listed
above.

Finally, it should be noted that there is no lock in involved in adopting a
prepend strategy. Either strategy can be transformed into the other. That
is, if you use the prepend strategy, you can later switch to an extend
strategy by writing your extensions (per Sean's instructions) and then
transforming your documents into your extended Docbook format.

Similarly, if you start with an extend strategy you can switch to a prepend
strategy by defining a custom markup language and then transforming your
extended Docbook documents into the custom language. Going this direction
may be somewhat more difficult, because going from looser to tighter markup
is harder than going from tighter to looser markup. However, it should still
be possible with a little care.

Notice that a successful prepend strategy depends on keeping the markup
small and tight. If the markup is small and tight then writing the
transformations into Docbook and other formats is simple and easy to
maintain. If you let the markup get loose and sloppy, however, then
programming the transformation becomes a big job and you start to lose your
ease of use and validation advantages. Several small tight topical prepended
languages are preferable to trying to create one big one, or to extend an
existing one. That road leads eventually to the recreation of Docbook, and
if you are going down that road you might as well skip the journey and jump
right to the destination. If your needs cannot be met by a small tight
topical markup language, then going the extend route may be the correct
strategy. Just don't be too quick to assume that you can't make topical
markup work for you.

Mark Baker
Analecta Communications


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP FOR FRAMEMAKER TRIAL NOW AVAILABLE!

RoboHelp for FrameMaker is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to online Help, intranet, and Web.
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! Call 800-718-4407 for
competitive pricing or download a trial at: http://www.ehelp.com/techwr-l4

---
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.



References:
Re: XML-based Help Authoring tools for customized help: From: Sean Wheller

Previous by Author: Re: PowerPoint Makes You Dumb?
Next by Author: Re: XML-based Help Authoring tools for customized help
Previous by Thread: Re: XML-based Help Authoring tools for customized help
Next by Thread: Re: XML-based Help Authoring tools for customized help


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


Sponsored Ads