Re: XML-based Help Authoring tools for customized help

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

Chris Gooch wrote:


>
> Q. Is DocBook a suitable application-specific language for doing
> technical documentation?
>
> Now, the simple answer I guess is yes, of course it was designed for that.
>...
> Does anyone have practical coal-face experience of using DocBook to:
>
> 1)   produce reference style pages for, say, APIs
>...
> 11)   enable customers to take docs and customise them themselves

This is a good list of questions, but I think it is useful to take a rather
large step back and ask some questions about the overall content development
process.

One of the key benefits of using standardized markup languages is that it
makes it much easier to do custom development of software to process
content. The question has rightly been asked, though, why you would want to
do such development when ready-made tools exist, both in the form of
commercial applications such as Word and Frame and in the form of existing
tools designed to work with DocBook. To provide a comprehensive answer, we
need to step back from the traditional document creation paradigm.

DocBook, and its associated tools and processes, mimic the production
process used in Frame and Word. That is, authors create documents by
directly entering information into the form of a document. Whether this is
done in WYSIWYG/direct style environment where authors directly describe the
appearance of the document, or whether it is done in a
style-sheet/template/DTD/schema environment, where information is entered
into a logical framework or a document, we are still in the realm of
document authoring.

(If is sometimes argued, that there is a gain in efficiency for authors in
using markup rather than WYSIWYG because it removes the need to worry about
formatting. However, many document-oriented markup approaches simply replace
the need for an explicit focus on document formatting with a need for an
explicit focus on document structure. The gain in efficiency may be dubious
at best.)

Now we all know that documented authoring is inefficient in many
circumstances for the following fundamental reasons:

* We now deliver to multiple media and multiple delivery vehicles, whose
structures do not always correspond to document structures
* The same information can occur in multiple documents within the same
product set and between different product sets.

A lot of work has been done in the areas of single sourcing and reuse to try
to address these inefficiencies. Most of these efforts have involved the
addition of some form of processing metadata to documents so that they can
be build differently for different media, or so that they can be composed by
assembling document fragments in different ways.

These mechanisms have forced the abandonment of the direct styling approach
to document creation, but it has been accomplished with equal success in
commercial applications based on stylesheets and templates and in both
commercial and open-source tools using DTDs and Schema.

But in both cases however, limits have been encountered because the creation
and storage of information in documents and sub-document components imposes
hard limits that cannot be overcome simply by moving from one
document-oriented system to another.

What we can do instead, if we want to make greater progress, is to move away
from document oriented approaches to information creation and move towards
capturing information about a particular subject and then building documents
of different sorts for different media and different delivery mechanisms for
different audiences.

Subject-oriented authoring can be much more efficient than document
authoring under the right circumstances (though by no means all
circumstances). However, subject oriented authoring requires that authors
insert information into subject-oriented containers. Subject-oriented markup
languages are an excellent candidate for creating such containers. And
because subjects are many and various, you will need to develop your own
subject oriented markup languages.

This is where ease of processing comes in. If you create content in
subject-oriented containers you will then need to transform it into document
oriented container in order to deliver it to a customer. Using a standard
generalized markup language (of which both SGML and XML are instances) to
describe your subject-oriented markup language, will make it much easier to
write your formatting routines.

There is also an intermediate case, BTW, and actually a fairly common one in
the markup world, where a subject-specific document-specific markup language
is the appropriate thing to use.

In my view, a broad generic document-oriented markup language does not have
enough advantages over today's DTP applications to be easily justified. It
may be competitive, but it isn't clearly superior.

The case for a generic document-oriented markup language however, come when
you create a system that consists of subject-oriented markup languages,
subject-specific document oriented markup languages, and a generic document
oriented markup language used together to cover a broad range of integrated
information development needs efficiently.

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.