Re: XML-based Help Authoring tools for customized help

[eric -dot- dunn -at- ca -dot- transport -dot- bombardier -dot- com]

Sean Wheller <seanwhe -at- yahoo -dot- com> wrote on 12/19/2003 05:43:43 AM:
> However, content is often reused outside the organisation.
>  Take for example an OEM who sells to a channel. That channel
>  may make valuable contributions to the content. Technically
>  they are a seperate organization. Would you teach them the
>  prepend language?

First consider internal needs then consider external needs. For example, in
heavy machinery and international standards there are four levels of
supplementary information: note, caution, warning, danger. We have many clients
that only recognize note and caution levels in their internal procedures.
Should we dumb-down the information in our documents to meet the needs of our
clients? Of course not. We develop the documents adding the most information
possible. Then, at output the structure can be transformed to meet client
requirements for reuse (In this case transforming Warnings and Dangers to
Cautions).
On our side however, the information remains available for reuse in documents
that recognize all four levels. Then, when transmitting the added urgency of
Warnings and Dangers is required, we need not go back and reanalyse all the
cautions to see if they warrant "promotion".
Same for the proposed prepend approach. Analyse your needs based on your
information and workflow requirements then see how to present the resulting
structure in the interchange standard.
To really simplify the point of sharing content with outside organisations,
consider the case of MSWord and FrameMaker. Both have interchange formats RTF
and MIF. If you're a FrameMaker shop and you know you'll have to eventually
deliver in MSWord do you perform all of your work in RTF? Of course not. You may
investigate if it's advantageous to change to a MSWord workflow, but otherwise,
you'll deal with the transformation when it's time to do the transformation. The
actual act anyway, the planning should be done in advance. :)
Similarly, if you want to create FM files from a database source do you build
your database using MIF? Once again, of course not. You design your database,
considering the future requirements, but structured on database and information
design principles.
Now I realise in the example the other organisation was providing "valuable
contributions" to the content. In that case, how the information is being
gathered and incorporated needs to be analysed. You'd need a granularity that
keeps responsibilities clearly defined. With clearly defined information
deliverables, the different organisations could very easily each be working with
completely different systems and exchanging with each other using an approved
interchange format.
Dealing with dozens of different suppliers, I can actually say that the best
answer to "Would you teach them the prepend language?" is Yes. If the structure
is clear, it may be the only way to have any control over the quality and
organisation of information that you receive.
Even if you use Docbook or another standard there will be a lot to teach your
collaborators about the specifics you require in your system to ensure that all
organisation is consistent. ATA has been brought up in the past and is a prime
example. While there is one giant inclusive generalised system/structure, a lot
of money is made consulting and implementing specific applications. A system
implementing one specific application may be incompatible with another system
implementing a different application. Even if they are both compliant with the
overall standard required by the ultimate customer.

Eric L. Dunn
Senior Technical Writer



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

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.