Re: XML-based Help Authoring tools for customized help

Subject: Re: XML-based Help Authoring tools for customized help
From: David Neeley <dbneeley -at- oddpost -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 18 Dec 2003 16:14:29 -0800 (PST)


Now the thread is getting to the heart of the issues, I believe, rather than mucking around about extremely artificial semantic questions regarding "whether DocBook is XML!"

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.

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.

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.

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.

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.

Therefore, I think it highly likely that as usual "the devil is in the details"--and that these decisions should be made very early in the process by people who understand the issues well enough to make them. Unfortunately, I have seen a relatively few people who have both the expertise and the budget of time and money to do so. 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.

Either way you proceed, I am not completely sanguine that a well-planned and -executed process is likely to exist in the majority of shops, which do not have the luxury of stopping everything while such a project is designed, implemented, and debugged.

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.

Regards,

David

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

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.



Follow-Ups:

References:
Re: XML-based Help Authoring tools for customized help: From: Mark Baker

Previous by Author: Re: Better to index in Word or Frame?
Next by Author: Re: Best Practice: Inserting graphics with Captions in Framemaker 7.0
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