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.
Subject:Re: More single sourcing From:"Bill Hall" <bill -dot- hall -at- hotkey -dot- net -dot- au> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Tue, 29 Jan 2002 20:49:04 +1100
Clare Attenborough says,
> [O]ur software
> is aimed at the developer community so most of our docs are written by the
> developers in the company and the doc dept then takes them and puts them
in
> a more readable format. The developers have stated a preference to
continue
> to write docs as a whole instead of in chunks of information. I'm looking
> for any suggestions as the best way of getting what they write into the
> single sourcing system. They could continue to write in Word of course and
> we could spend many happy hours cutting and pasting and tagging, but if
> anyone has any suggestions for a better system, input would be
appreciated.
Clare's authoring environment is similar to the model we used to follow for
drafting ship equipment maintenance procedures. This was replaced by an SGML
authoring environment (FrameMaker+SGML - supported by a content management
system - http://www.simdb.com/), as described in my May 2001 Technical
Communication paper - http://www.tenix.com/PDFLibrary/91.pdf. Assuming you
can use an existing DTD for your work (e.g., DocBook) or have someone
in-house who can develop one for your own requirements, I suggest that you
try an application like ArborText's Epic Editor, SoftQuad's XMetaL (now
owned by Corel) or FrameMaker+SGML. If DocBook is suitable, you can probably
find the necessary SGML or XML applications to make it work on any of these
three systems.
Even without content management/single sourcing, if you have
software/hardware engineers doing much of the authoring the value
proposition is quite clear.
Assuming that you set up your system to prevent authors from changing house
styles or convince them that they have noting to do with styles, based on
Tenix's experience with this kind of conversion, it should only take a week
or two to bring naive authors up to speed in the structured authoring
environment. As implemented, your structured authoring environment will show
the authors approximately what their document will look like, but the only
things they can do are select structural element and type text into them -
and the structural elements have to make sense where your DTD is concerned.
The main educational problems are to get the engineers to think about
document structure instead of document appearance, and to convince them that
output formatting is not their concern.
Costs are
(1) Licensing for the number of seats you need for the structured authoring
environment,
(2) Establishing what DTD(s) and output format(s) you need. This may involve
some consultancy to analyse your documents, and build your output formats if
you have no in-house skills.
(3) Staff training. Note: Authors need much less training for an FM+SGML or
other DTD controlled environment compared to a word processing environment,
because the author has no formatting responsibilities. They only select
structural elements according to the DTD's rules (and the good editing
environments will show you what is allowed and won't let you break the
rules) and type text into them. Estimate two days formal (we did it in half
a day) followed by hand holding for a week or two before they surpass their
productivity in a word processing environment.
Benefits are:
(1) Substantially improved quality - editors focus purely on content and
have no formatting problems to fix. Deliver better product with less editing
costs.
(2) Cut author labour by at least 50% by eliminating formatting worries and
stuff-ups.
(3) If you do have a content management/single-sourcing environment other
savings are possible.
Whether you should convert your legacy documents is another question
entirely. In our case, where our 4,000+ original documents already had a lot
of structure imposed on them by an existing merge table structure, automated
conversion - although it cost a lot to program - certainly proved to be cost
effective. For a smaller and less structured document set, it would probably
be more cost effective to use manual cut&paste to move texts into your
structured environment.
Assuming you don't spend megabucks on content management and you don't go
over the top with DTDs, in the kind of environment you describe, the cost to
implement a structured authoring environment should pay off its investment
in less than a year.
In Tenix's environment for authoring maintenance procedures, we are now
delivering configuration managed (country, ship and engineering specific)
maintenance procedures plus producing a number of derivative extracts from a
single set of maintenance routines. Some of the results of our
implementation, including the workflow we followed can be found on: http://www.planetmarkup.com/xmlarena/xap/Friday/MaintenanceDocumentationMana
gement.pdf -(includes a number of screen shots from the original
implementation); http://www.binarything.com/binarything/openpublish/OpenPublish2001a.pdf -
(more focus on what we are doing now).
For information on using DocBook and many other resources and opinions on
structured authoring try the xml-docs forum. http://groups.yahoo.com/group/xml-doc/. For the op-ed side of the
single-sourcing/structured authoring search Techwr-l archives for "real
value". Andrew Plato and others have raised many of the pitfalls you will
have to consider in making a business case. You can also learn a lot about
FrameMaker+SGML by searching the various FrameMaker forums for FM+SGML and
FrameMaker+SGML.
I hope this helps,
Bill Hall
Documentation Systems Analyst
Strategy and Development
Tenix Defence
Yarra Tower, World Trade Centre
Melbourne, Vic. 3005 Australia mailto:bill -dot- hall -at- hotkey -dot- net -dot- au mailto:bill -dot- hall -at- tenix -dot- com
(Note: I'm on holiday, and won't return to Tenix until 18 February.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Attention ForeHelp and Doc-to-Help Users! Upgrade your existing product to
RoboHelp for only $299, through January 31st. RoboHelp can import your
existing Help projects! Learn how else RoboHelp can benefit you. www.ehelp.com/techwr
---
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.
