Re: XML-based Help Authoring tools for customized help

Subject: Re: XML-based Help Authoring tools for customized help
From: Sean Wheller <seanwhe -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 19 Dec 2003 11:18:18 -0800 (PST)

From: <eric -dot- dunn -at- ca -dot- transport -dot- bombardier -dot- com>
> Now I realise in the example the other organisation
was providing
> contributions" to the content. In that case, how the
information is being
> gathered and incorporated needs to be analysed.
You'd need a granularity
> 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
> interchange format.

In my case external members would access XML documents
using CVS or Webdav.
There is no need to save to another format. They just
work in the Docbook
XML instance. When it is saved, the version is bumped
up. I can always use
diff to see changes.

Another aspect of this is that the channel can also
create requirement
specific documents. This mostly involves collecting
released content
components into a new document. This is done by
reference. They do not need
the technical authors to get involved. When they
create a document that is
requirement specific, it is saved in the repository
where it becomes
available to everyone in the organisation. It has the
very powerful effect
of accelerating content development around the
product. Content that would
not normally be core part of product development and
would not normally be
provided in a time frame that is reasonable (I see
techpubs as part of
product development). I am certain that we have all
experienced cases where
we have to stop developing core product to satisfy
urgent needs. Some are
warrented, but most are just a nusance and put extra
pressure on the
development schedule.

There are also instances where new content components
are created. Some of
these become very valuable building blocks that
significantly reduce the
time required to deliver core product documentation.

> Dealing with dozens of different suppliers, I can
actually say that the
> answer to "Would you teach them the prepend
language?" is Yes. If the
> 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
> collaborators about the specifics you require in
your system to ensure
that all
> organisation is consistent.

Normally, a Markup Style Guide is provided something
along the lines of the
KDE Markup Guide. Consistency for core product content
components is
provided by the authors, who review all contributions.

Aside from all these debates. I would like to note one
more thing we have
not mentioned, and that is Literate Programming. I
believe that it could be
extremely beneficial with streamlining the maintenance
of large API
documents. I have not used this technique just because
I have not had the
opportunity to implement a system of such nature. I
was wondering if anyone
has experiences they may share on the subject?

This changes tack of the discussion. But I think we
are going around in
square circles. Not to say that there is a right or a
wrong, just that we
can only beat this bush so much. Any takers on

Sean Wheller

Do you Yahoo!?
New Yahoo! Photos - easier uploading and sharing.



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:

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 for more resources and info.

Previous by Author: Re: XML-based Help Authoring tools for customized help
Next by Author: Re: Antwort: Do you permit SMEs to revise your drafts?
Previous by Thread: Re: XML-based Help Authoring tools for customized help
Next by Thread: No active TOC links using RD fields in Word?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads