Re: XML-based Help Authoring tools for customized help

["Mark Baker" <listsub -at- analecta -dot- com>]

 David Neeley wrote:

> I believe that for some situations, Mark's approach to have a simplified
prepend language makes
> great sense. I am *not* sure, however, that the illustration about
"automatically scanning and realizing
> an ingredient is hazardous and inserting a warning" is particularly
helpful in many occasions. For
> example, in an involved petrochemical process many hazardous substances
are mentioned
> throughout--an automatic insertion of warnings seems to me to be fairly
awkward and most
> probably excessive in such a case.

It's all a matter of doing it intelligently. It is not difficult to specify
rules for where and when generated content should be included. An example of
a more interesting problem is to deal with cases where it is a particular
combination of chemicals that triggers a warning rather than one alone. But
by the same token, those are the circumstances where it is easiest for a
human author to make a mistake. There is a reason that pharmacies use a
computer to check for drug interactions when they fill a prescription.

But the example given was not meant to illustrate a complete process, only
to demonstrate that there is a another potential degree of separation
between information and presentation, and that it has potential value both
in terms of efficiency and accuracy. Warnings was the first example I could
think off where there was an easy to understand example at each degree of
separation.

> In addition, many documentation departments must deal with a wide variety
of subjects that often
> do not lend themselves to a particularly simple tagging language. In such
a case, as various
> extensions are identified as being necessary, the "tight" and focused tag
language would seem
> to take on a life of its own--resulting in something well beyond its first
incarnation.

It is certainly true that you have to be disciplined about it. It is also
true that these languages do need to be refactored from time to time. But
with a thorough and disciplined refactoring of the content, you would be
surprised what can actually be accomplished. There may be cases where it
doesn't work, and cases where it's not worth doing. But it works well for a
lot of cases.

> Next, I am not persuaded that in many cases it is a particularly easy
thing to develop such a
> language. Try as we might, when considering the many different use cases
in documentation,
> many things will be forgotten and thus constant upgrade would seem
necessary. This, of course,
> plays hell with the entire tool chain--soon obviating the original
advantages of a "simple" tag language.

It takes time to learn how to do topical markup. Initial attempts at topical
languages often fall into the trap of putting a topical overlay over a
document structure -- and that frequently leads to disaster (though there
are places where it is applicable). Topical languages must be topically
oriented, not document oriented. It takes a while to learn to think that
way.

And yes, periodic refactoring of the content is often needed. But -- and
this is a really important point -- it does not play hell with the entire
tool chain. This is what is important about a layered approach. The prepend
strategy introduces a new layer at the front of the publishing chain. Churn
in that layer is isolated from the rest of the chain. An extend strategy, on
the other hand, does involve making changes in the downstream parts of the
chain, and can cause problems. This is one of the advantages of the prepend
strategy.

> I am entirely in agreement that many of the decisions should be removed
from the typical author's
> ken. I would if I could remove all formatting capability from them and put
that in the hands of the
> part of the process charged with the final output product in terms of
media and format.

Absolutely, and I would point out that document structure is also something
that can be removed from the author's ken (in many cases, though not all).

> However, it seems to me that as you begin to develop these custom tag
languages, if your
> information needs are as diverse as in most shops I've seen you will soon
either have a plethora
> of individual tag languages or the product will soon become somewhat as
complex as a
> Simplified DocBook. Therefore, it seems to me that it may be as good to
start with such a
> base--selecting the dialect that is closest to your need as possible.

The point is not to have a simple system. The point is to have a system with
simple interfaces. If the interfaces are simple, it matters much less that
there are several of them. Indeed, internal complexity is sometimes the
price you pay -- quite deliberately -- to achieve external simplicity.
Today's cars are much simpler to drive than those of 50 years ago precisely
because they are so much more complex inside. Again, it really is all about
what part of the system you are trying to optimize. And that, of course,
will vary from one circumstance to another.

Having worked with both strategies, I can tell you that this strategy does
work. I've done it, and seen it done, successfully. Like anything else, it
seems a lot easier once you have had the experience of going through it.

> In most cases, the single largest problem is the existing information base
and converting it to a new paradigm while also continuing to stay on top of
requirements for updates and new documentation.

Absolutely, which is why I believe in a approach based on a gradual
refactoring of content to a new system rather than a wholesale migration.
Gradual refactoring also gives you a chance to learn more about your content
and its structure, and to get better at topical markup. It becomes an
exercise in continuous improvement rather than a one-time switch.

> All of which said, I believe that any thorough analysis of moving a
documentational information
> corpus into the present generation of capabilities should indeed
contemplate what process makes
> the most sense for the organization, its needs, and its capabilities. I
simply don't view it as such a
> clear-cut "either/or" situation in the real world.

It's not a clear cut either/or. As I said, I presented an alternative
strategy and stated the reasons why I preferred it. And I made the point
that the strategy you choose depends on what part of the system you are
trying to optimize.

I think we both agree that anyone who simply decides to move their
documentation to XML without any well considered business reason is making a
mistake. So the questions each person has to ask are, what business
objectives am I trying to accomplish. What parts of my process do I want to
optimize. What tools and methods exist to let me create that optimized
process.

One of the important things we can do here is to make sure people are aware
of all the options.

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.