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 18:54:17 -0500
Sean Wheller wrote:
>
> Isn't this true of any tool?
Yes. That is why tool changes are expensive and have to be carefully
considered.
> Authors don't seam to have a problem with migrating
> from styles in Word to
> Tag Elements. The concepts are much the same.
For stype-orineted markup, they are much the same. A lot of markup that
pretends to be semantic in nature is really just style markup with semantic
hinting in the style name. It is not actually useful for anything other than
the application of styles to the text. Style names in Word can be given the
same semantically-hinted names for the same effect.
> I do assume their brains have developed beyond
> the formative stage you
> used as an analogy in the above text. Geeze, just
> walking at that age took
> all my processing power. :-).
On the contrary, our ability to learn language is at its highest in our
youth and declines rapidly as we age. This is a consideration that has to be
taken seriously when designing a language based solution to a problem.
> In
> addition, because of
> the DTD/XSD, markup cannot be misused.
I wish this was so, but it isnt. Here's how the though process goes: I want
this paragraph in italic. I don't have an italic-paragraph tag, but I know
that the caption tag produces italic text, so I'll use that. If the caption
tag can only be used with a table, I'll create an empty table. No one will
see the difference on paper.
This, and a thousand other cheats and mistakes happen all the time. The
DTD/XSD can't catch them. They can only catch invalid structure, not invalid
intention. And the more lenient the structure, and the more elements it
contains, the easier it is to cheat or mistake its intention. That is why
small, tight, topical markup is preferable. It is harder to cheat and harder
to make mistakes.
> Change, learning and adapting are harder
> tasks for some people that
> for others. However, given the training, most will
> adapt and will eventually
> learn a new way of writing.
True. But it is still important to reduce training costs and minimize mean
time to productivity by creating tools that are as easy as possible to use.
To simply say, "most will adapt and will eventually learn" is fiscally
irresponsible. We are supposed to be usability champions. We shouldn't take
cavalier attitudes to usability like that.
> Related to this is the problem of XSL and
> transformation. Many of the
> authors like to control the layout, formatting etc.
> Using xsl:param and
> xsl:template in a customization layer to override the
> vanilla design
> elements of the distribution is not easy for many
> people. Hell, even some
> gurus get lost.
Yes. Big, loose tagging languages are hard to process as well as being hard
to use. Small, tight, and topic wins on this front as well.
> When you consider that most authors
> are accustomed to using
> a format dialog where with a few changes and a click
> of the OK button
> updates the screen and reflects the choices they have
> made, you can
> understand why this apparent lack of formatting
> control is disconcerting.
My experience is that if a tagging language looks like it is describing a
document, people want to control the formatting aspects of that document and
get frustrated that they cannot. With a small tight topical language that
clearly is meant only to capture information and not to describe a document,
they stop worrying and let the system take care of things for them. YMMV.
Frankly, Docbook has its place, just as Frame and Word have their places.
They are all packaged systems that expose their inner working enough so that
expert users can make them do interesting things. The expert users of each
system tend to become fervent advocates of those systems and suggest them as
ideal solutions to a wide range of problems.
XML, on the other hand, is really about the ability to roll your own markup
languages that are specific to your needs. If your needs are just like many
other people's needs (and many people's are) then one of the packaged
systems will probably meet those needs. If not, then a custom markup
language is in order. And for the sake of both the author and the person who
has to program the processing of that language, it should be designed to be
small, tight, and topical.
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.
