Re: XML-based Help Authoring tools for customized help

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

Bill Lawrence wrote:

> The great advantage of Docbook, TEI, DITA, ThML, and heaven knows what
> else is that they are standards.  There are readily available tools,
> books, training courses, discussion lists, users groups,
> people-who-already-know-the-technology-to-be-hired, etc.

Actually, what they are is out of the box applications with specific
semantics. If their semantics suit your present problem then you can go
ahead and use them. In the database world, there are many out of the box
database systems on the market and they are used very successfully to
address a large number of business problems. These included both open source
and commercial efforts and both proprietary and standards-based data
formats. But there are also a large number of custom built and activly
maintained databases. They are created not because people just decided they
didn't want to purchase off the shelf, but because they had unique problems
and off the shelf systems didn't meet their needs. It is the same with
content. For some content, off the shelf solutions fit. For other content,
they don't.

> A custom
> built, scaled-down, lean tagging structure carefully tailored to an
> individual environment and task is certainly grist for the mill of many
> papers (and will line the pockets of many consultants), but the ongoing
> maintenance is going to be a nightmare. You'll be endlessly refactoring
> the thing and all bets are off when the creator/maintainer goes away.

But the thing is, most organizations creating documentation today do create
their own carefully tailored tagging structure. They just don't do it in
XML. They do it in Frame or Word by creating templates or stylesheets. Now
Frame templates don't have the same hierearchical relationship that Docbook
elements have, but they serve very much the same purpose: they allow you to
abstract the final appearance of your document by applying named styles to
content elements.

Adopting Docbook, then, is like buying a copy of Frame and finding that
there is only one template that has been decided on in advance by Abobe, and
everyone is expected to use it. Yes, you can change the definitions of the
styles, but not the set of stylenames. Oh, and by the way, Adobe does not
guarantee that the template will be the same from one verion of Frame to the
next. It may introduce backward incompatible changes in the next version.

Any system designed to manage a large volume of information in a consistent
fashion requires ongoing maintenance and refactoring. This is a significant
part of the work involved in running a documentation organization today and
it always will be.

> All of your transformation and data manipulation tools must be built
> from scratch.  Trust me, I've done it both ways and you really need to
> put a gun to my head to get me to build a schema from scratch again.

Well, I've done it both ways too and, trust me, a well designed system that
meets your current business needs is always the way to go. If you can buy
that system off the shelf, great. If not, build it yourself. The reason that
a custom system is sometimes the way to go is that building the processing
tools is not the biggest part of the work. Creating and managing the content
is the biggest part of the work. The custom development work is worth it if
it makes the content creation and delivery work significantly more
effective.

> If custom DTDs or schemas were truly a good idea for the bulk of the
> organizations in our business, most big software and hardware companies
> would do that instead of embracing a standard such as Docbook or TEI.
> Instead, they embrace the standard and place people on the committee for
> that standard.

Right now, unfortunately, a lot of people are focussed on "moving to XML"
without any clear idea of why they are doing it. I'm not interested in XML
for XML's sake. I'm interested in efficient creation and management of
documentation. If your priorites are to move to XML and to embrace a
standard, then by all means move to Docbook. You will have accomplished your
aims.

If, however, you are looking to improve the efficiency of your documentation
organization while producing more customized information products, you may
well find that the process you need to implement requires a custom data
model. The point is, you start with the process. If the process analysis
shows that a standard document-oriented approach is warranted, you can then
look at Frame, Word, DocBook, etc. and see which one suits you best. If it
shows that you need a custom data model, then you need a custom data model.
So you create one.

My only point about DocBook, at the start of this discussion, was that if
you are creating your own tagging language, you will need to include some
basic text structure markup. And my point was, don't borrow it from Docbook
because Docbook's structures are to complicated. Borrow it from HTML.

I did make the point that if you are going to create a generic document
markup, it is going to need to be as big as Docbook is and as loose as
Docbook is, just in the nature of the thing. But for the text structures of
a custom language, something smaller and tighter is more appropriate. That
is the actual point I was making, and I stick by it.

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.