XML-based Help Authoring tools for customized help

[Chris Gooch <chris -dot- gooch -at- lightworkdesign -dot- com>]

First of all, thanks to all the contributors to this thread. It's
the most imformative (and informed!) and useful discussion
on this list for a very long time IMHO.

Now, without wishing to re-ignite heated debate on whether
DocBook "is" XML, here is my take on the subject;

XML is a metalanguage (i.e., a language used to describe
		other languages) - and in fact it's a simplified
		form of SGML but that's neither here nore there

DocBook is a language for describing technical documents
		(which could be specified in XML or SGML)

HTML is a language for describing web pages

MATHML is a language for describing mathematics.

SVG is a language for describing vector graphics.

All of the above are langauges for particular jobs, and were designed
so as to be easy to express in the XML/SGML way of doing things.
Other languages exist for similar jobs, e.g., LaTeX for documents,
web pages and mathematics, postscript for vector graphics, but these
languages happen not to have been designed to be parsable in an
XML/SGML kind of way.

In the XML world there are many shared languages / vocabularies / DTDs /
schemas (call 'em what you will) springing up for different interest groups
to communicate in, and using XML to describe all these languages means
they all have common roots and thus are easier to work with, when you've
seen one you have a clue about others too, and similar tools can be used,
etc. etc. etc.

Having got that out of the way...

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.
And I take the point about Simplified DocBook and also about using that
as a starting point and adding your own semantic markup for elements
you need to mark semantically.

But then if I give my doc to another technical writer somewhere in the
world,
they would need to know my extensions (so like, that's OK I give them the
DTD along with the file just as I'd give them the style file along with a
LaTeX
file or a .dot along with a .doc).

Does anyone have practical coal-face experience of using DocBook to:

1)   produce reference style pages for, say, APIs
2)   produce longer, more "document" oriented "how-to" guides
3)   produce white papers
4)   produce robohelp style help for end-user apps and demos
5)   produce robohelp style help for user-interface widgets
6)   embed reference documentation in source code
7)   encode FAQ data
8)   encode all the marketing collateral etc. for the web site
9)   make sending data to translation houses easy
10)   make provision of customised docs for particular customers easy
11)   enable customers to take docs and customise them themselves

Now I suspect the answer might be no as I've specified too many things.
But if we're to assume for a moment that these are the kinds of
things that technical writers would want to do, then is it possible to
design a mark-up language which would form a suitable base (if not
DocBook), or is that too big an ask and horses for courses should be
the name of the game?

Anyway what I'm wondering is, what are people actually managing to
achieve? (for example, using DocBook). I would at this point find that
more instructive than further philosophical debate (I can see where
everyone stands I think).

thanks for an informative discussion,
Chris.

Christopher Gooch, Technical Author
LightWork Design, Sheffield, UK.
www.lightworkdesign.com



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

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.