RE: XML and Documentation

Subject: RE: XML and Documentation
From: Kevin McLauchlan <kmclauchlan -at- safenet-inc -dot- com>
To: 'Chris Vickery' <cvickery -at- arenasolutions -dot- com>, Melissa Nelson <melmis36 -at- hotmail -dot- com>, techwr-l -at- lists -dot- techwr-l -dot- com
Date: Fri, 9 Feb 2007 16:18:26 -0500

Stream-of-unconsciousness follows...

Chris Vickery replied to Melissa Nelson
> A great starting point would be to google for DITA business case or
> Docbook business case. You can sell your boss on the fact that your
> productivity will increase as you separate content from
> formatting, and
> eliminate desktop publishing costs.
> You can create XML content that is then formatted via XSLT to produce
> HTML and help content, and via FO to create PDF output like user
> manuals, all from the same XML. By reusing the same content, you only
> have to update a single source file, and it is updated in each
> deliverable in which it is used.
> To give you an idea of the ease of use, I new about zero
> about HTML and
> dove straight in to XML Docbook (with the help of a knowledgeable
> teacher).
> There are lots of resources out there on the advantages of XML. Check
> Oasis.

That's actually the kind of talk that used to put me off, when
XML first became a hot buzz-word.
I was using FrameMaker, and not even the structured version
- well, I had it, but I wasn't using those features; I was
just faking structure. It worked fine. As an only writer, I had
no real incentive to switch over to something different.

However, by virtue of some corporate take-overs, I got sucked into
an environment that had lots of Word docs, some of which I inherited.

Hmm. I could slowly pull dozens of Word docs into FrameMaker,
or I could re-work them in Word to make rigorous use of styles,
or I could muddle along until something better suggested itself.

Inertia won for a while. Then hit version 2,
and "something better" seemed to have arrived.

It happens that OOo does pretty well everything useful that Word
does, only better and more reliably. OOo also stores documents in
an XML format, by default.

So, I'm working as a techwriter, using OOo as a word-processor,
and just incidentally working in an XML environment. When the
day comes (if ever) that I switch from OOo, my document source
files will be ready for another XML front-end to inhale them.
At that time, I might or might not need to worry about XSLT and
other formatting frameworks. More likely, they'll be "under-the-hood"
of whatever authoring tool I'm using at that future time.

The point is that XML as an environment (as opposed to XML as
a standard) is now far enough along that one can get
acquainted with the various X-this-and-that if one is geekish,
but one can just as easily turn to writerly tools that just
happen to incorporate the needed functions, transparently,
while preserving the portability and re-usuability of XML.
In other words, you could switch painlessly without needing
to lift the skirts of Docbook or DITA or... or... or....

Of course, OOo is also quite mature as a word processor (and
all those other office tools it includes), including a fair
simulation of MS Word... So, while it encourages you to be
rigorous about your writing, and to use Styles for everything,
it nevertheless permits you to mess it all up with local/spot
formatting... and it will happily save THAT in XML.

I'm looking for a "discipline" feature/switch in OOo that
will let me "force" the use of styles, by default, and only
permit spot-formatting overrides on a per-incident basis, and
then only after an admission of guilt/evil on the part of the
person doing the dirty deed.

In fact, I think I'll start a discussion about that right
now, over on the OOo [users] list. :-)


The information contained in this electronic mail transmission may be privileged and confidential, and therefore, protected from disclosure. If you have received this communication in error, please notify us immediately by replying to this message and deleting it from your computer without copying or disclosing it.

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output.

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help &amp; Manual:

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Previous by Author: RE: Word to OpenOffice - what to do with styles?
Next by Author: RE: Current trends in Authoring Tools?
Previous by Thread: RE: XML and Documentation
Next by Thread: Selling a team on the technical writing job role

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

Sponsored Ads