TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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, 11 Dec 2003 12:08:24 -0500
Bill Lawrence wrote
> There is actually a fourth option. One can subset an existing tagging
> structure, such as Docbook.
That is true, but in the case where you need custom elements in addition to
the basics, you are then in a position of creating a superset of a subset
and I am not convinced you are any better off with that than you are with
creating your own, even in terms of initial investment.
What you say about authors is certainly true. Some can handle more
complexity than others. But complexity is never a good thing for authors,
even if they can handle it. I am a strong believer in a rigorously lean
approach to markup that is focused entirely on author needs and author
productivity. That, after all, is what this is really all about. If your
system does not improve author productivity, what is the point? You might as
well stay with DTP tools.
We know that the later in any process that a mistake gets caught, the more
expensive it is to fix. It follows that the number one thing we can do to
make sure that our authoring systems are efficient is to ensure that authors
make few mistakes and that the mistakes they do make are caught early. We
also know that authors using complex markup languages make lots of mistakes,
and sometimes cheat deliberately. We know that these mistakes are often not
caught until late in the process and are expensive to fix. Your mileage may
vary, but this phenomena is well known and often complained of. To reduce
author error, we need a markup that has the following properties:
* Small -- easy to learn (and incidentally easy to process)
* Tight -- few options, and easy to validate
* Topical -- The markup asks for information the authors know in a language
they understand.
It is not hit on Docbook to say that it is not small, tight, and topical. A
generic markup language cannot be. It is just that big, loose, general
markup languages do not lend themselves to efficient authoring and should
not be used at the author facing end of the system. (They may well have
important downstream uses, as generalized document descriptions against
which stable formatting routines can be written.)
Going with an off the shelf markup language may seem like a way of getting a
head start. Unfortunately, it is often a head start down the wrong road.
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.
