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 16:38:57 -0500

Sean Wheller wrote:

> I cannot understand why, with advent of Relax NG and
> NRL, anyone would want
> to adopt a prepend stratergy.

Well, RelaxNG and NRL really have nothing to do with it. You see, I'm really
not trying to make markup work or to solve problems in the markup space.
What I am trying to do is to make authoring work. What I am looking for is
an approach to authoring which is:

* minimally invasive of the authoring process itself
* captures the richest semantics for the least effort
* catches problems as early as possible.

Now the best way to do that is not always to use markup at all. Sometimes a
forms based interface works best, for example. Sometimes, however, markup
does provide a solution. But that markup needs to be small, tight, and
topical, and the best way to make markup small, tight, and topical is to
design very small very specific languages for the problems at hand.

So my proposal has nothing to do with finding "the right way" to do markup.
It is all about authoring, and my experience, looking at things from this
perspective, tells me that this approach works.

> It just does not make sense to write yet another
> language for authoring and
> publishing, just to transform it to another neutral
> format or publishing
> language.

Not from one neutral format to another. From a topical format to neutral
format. A topical language is specific to its subject matter. It makes
authoring easier because it asks the author for information in terms that
they understand as a subject matter expert.

Look at it this way, every step in the publishing chain takes information
that is subject-oriented in nature and turns it into information that is
presentation oriented in nature.

Consider the following scenarios:

1. I sit on a chair and it breaks. I pick myself up and go make a sign to
put on the chair. I write "Broken" in big red letters and attach the sign to
the chair. I have translated my subject matter expertise about the broken
chair into a set of presentation and formatting decisions in one step.

2. I am writing a manual in Word. I write a procedure that involves a
hazardous chemical. I know that the chemical is hazardous, so I create a
table to contain a warning. In the right hand cell I import a warning
graphic. In the left hand cell I type in a warning text, and apply the
warning style to the text. Here I have one degree of separation between my
subject matter expertise and the presentation decisions. The stylesheet
contains the specific formatting choices for a warning. I don't decide how
to format a warning, I just style the text as a warning.

3. I am writing the same manual in a document-oriented markup language. I
write a procedure that involves a hazardous chemical. I know that the
chemical is hazardous, so I create a warning element and type in the warning
text. The formatting routine will style the text and import the proper
graphic. Here I have another degree of separation.

4. I am writing a manual in a document-oriented markup language. I write a
procedure that involves a hazardous chemical. I know that the chemical is
hazardous, so I create a warning element. I also know that I have a standard
library of warning elements so I insert the appropriate text entity
"&hazardous-chemical-warning;". Another degree of separation.

5. Now here's the final degree of separation. I am no longer writing in a
document oriented markup language but in a topical markup language. I write
the procedure, making up each of the elements used with topical markup. I do
not insert a warning. There is no place in the markup to insert any warning.
However, when the markup is processed, the topical markup is scanned and the
processing script sees that one of the materials used in this procedure is a
hazardous chemical and it automatically generates and inserts the warning.
This is the final degree of separation. My subject matter expertise in the
procedure is expressed in topical markup. I make no presentation decisions.
Someone else's subject matter expertise about the hazard of the chemical are
expressed in another topical markup language. The need for a warning in my
procedure is deduced by looking at the two pieces of data. The presentation
is generated in the appropriate format automatically. The potential for me
to forget this important warning is greatly reduced.

Using topical markup is all about adding one more degree of separation
between the author and the presentation.

> It seams a bit overkill. Why not just adopt
> standards and learn to
> use them?

It depends on which activity you are trying to optimize. If you are trying
to reduce the amount of markup processing code you have to write, you might
have a point. On the other hand, it is not a given that the work involved to
translate the prepended language into Docbook is going to be greater than
the work to extend the Docbook stylesheets. It might be more, it might be

But I am not trying to reduce the amount of processing code in the system.
In fact, I am trying to put as much of the work as possible in the
processing code and take as much as possible away from the author.

Learning to use a topical markup language can often be reduced to under an
half an hour. It is throw away knowledge. If you use it infrequently, you
can forget it and learn it all over again next time you need it. (Wiki
markup is like this. I never remember it, but I can relearn it in five
minutes.) Learning Docbook, and leaning how to map your subject matter
knowledge onto Docbook structures in the way that your organization wants
take significantly longer. It isn't throw away knowledge. I can't just pick
it up again next time I need it, so unless I am using it every day, I'm
going to have a hard time maintaining my knowledge.

(Wiki's, BTW, are a good example of a prepend strategy at work. Rather then
extend or subset HTML, WIKI markup is prepended to HTML and translated into
HTML by a WIKI processor. This is much less work, both for development, and
for users, than using an extended HTML.)

Of course, once you, as an individual writer, having mastered Docbook, and
assuming you use it regularly so that the knowledge stays fresh, and
assuming you have a technical bent and don't mind working with all this
stuff, these arguments may not seem very persuasive. But from the point of
view of an information development manager with many different contributors,
with writers of different levels of technical aptitude, and with budget,
time, and quality constrains to consider, these can be very important
issues. It is all about finding the right place to spend your resources to
solve the problem you have in front of you.

> The prepend route seams to add just one more vocab
> that people must learn.

No, it replaces one with another. Writers learn the prepended language
instead of Docbook, not in addition to it. But the real point is that it
optimizes the language for learnability. Specifically, because the prepended
language is topical, it matches the subject matter expertise of the author.
Thus it leverages their subject matter knowledge to help them learn the
language and to help them capture the information they are providing.

Learning is optimized when the subject matter matches the learner's
experience. This is one of the key virtues of topical markup languages.

> The value of learning this language is limit to the
> confirmes of the
> operating environment in which it is used.

Yes. But why would it need to have value outside the confines in which it is
used? That is precisely where you want to deliver maximum value. Topical
languages deliver maximum value in a carefully targeted fashion to the exact
people who need them.

> In
> addition, your format must
> first be transformed before it can be shared.

Yes. But that is what machines are for. Machines should work hard to make
life easier for people. If I can make life easier for the writer to write
and for the reader to read then I have no problem making the machines work
harder in between.

> Then
> when you receive content
> back it must be transformed back to the prepend
> language. Why not just skip
> all that, cut to the chase.

I'm not certain what you mean here. Where would the content be coming back
from? Why would it have changed? It would pass through review in the prepend
format as much as possible, since that is where the semantics are captured.
Review of the assembled format might also be required. But why would that
result in a change in the content? Please clarify the scenario and I will
try to address it.

> People like James Clark, Norman Walsh, and Michael Kay
> are super experts
> participating in shaping the industry. If people like
> these don't use a
> prepend model, why should the mainstream do
> differently.

With respect, and I do respect their work, these are people who are trying
to make markup work. They are trying to push the boundaries of what can be
accomplished in the markup family. That simply isn't the problem I am trying
to solve. I'm trying to make authoring work.

It is interesting to note, however, that James Clark has stated that he does
not write RelaxNG schemas directly in XML because the syntax is to complex.
Instead he has created a simpler non-XML notation in which he develops the
schema, and then transforms it into RelaxNG. So there you have a case of at
least one of these gentlemen using a prepend strategy.

> I understand that the prepend model is possible, but
> man I can't see anyone
> going this route for publishing.

Hopefully some of the examples I have given above will help to explain the
value of this approach. If you have some other scenarios you would like to
explore, I would be happy to address them.

Mark Baker
Analecta Communications



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:

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 for more resources and info.


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

Previous by Author: Re: XML-based Help Authoring tools for customized help
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