Fwd: [astcq-discuss] Re: Distributed authoring using Word and Domino?
geoff -at- userdox -dot- com
"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Fri, 11 Jul 2003 09:30:36 +1000
X-Posted: Word-PC, Techwr-L, astcq-discuss.
Thanks Susan, you stated the problem exactly. As with a number of other
people, you have also raised very important issues. Detailed management and
procedural requirements are being investigated by my team leader. A few others
have responded off-list saying they are in a similar position. Yesterday I
emailed my TL with my notes - basically just a brain dump to help her prepare a
response for management. Remembering that many of the issues that have been
raised in these forums are being investigated by my TL, and this is specific to
my work environment, here is a sanitised version of that email. It might help
others in the same position.
I've done some quick analysis of the documentation system you mentioned. Here
are my opinions. Please note that all of these can be expaned upon if I have
The Word/Domino Model
This model is based upon using Word as a document editer, and Domino as a
versioning and distribution system.
Using Word and Domino in a distributed authoring environment is initially
attractive because they are already rolled out within AAA. Further
investigation indicates that using these tools will most likely cause losses in
productivity, quality, and an increase in costs.
The images used by core documentation are created by following a specific
procedure. They are then linked to the Word documents for ease of
maintenance. Distributed authors are unlikely to follow the correct procedures
(even when it is written down for them), and Domino prevents the linking of
images to Word documents. The linked images are single sourced, allowing one
image to be used in many documents. When the image is updated, every document
automatically gets the updated image during finalisation. Being unable to link
images would require some method (register) to track the name and location of
every image used in the document set. Without this time consuming register the
images very easily become inaccurate and/or out-of-date.
Embedding images is the only option if linking is not available. Embedding
images increases file size. Core documents average 4KB/page in size due to
linking/embedding. Training documents average closer to 15KB/page in size due
to pure embedding. Embedding also increases the chances of document corruption.
In a distributed environment it is not possible to ask the writer sitting next
to you what changes they have made to a document, forcing each change to be
versioned. 10 authors making 15 changes each to each document = 10(authors)*15
(changes)*268(files for core only)*300(avg file size in KB) = 11GB of versioned
files per release, made up of 40,200 files per release. This is a nightmare to
work with and manage. Different processes would need to be created to overcome
If versioning is not required, but check-in/check-out is required, Domino or
CVS are both suitable tools.
It is not possible to implement standards in a distributed environment of non-
professional writers. It is difficult, but possible, to do so with
Single sourcing is not possible under this model.
Speed of Use
It currently takes a long time to find and open a document stored on Domino
(Brisbane). How long will it take to open a document stored on Domino
(Gallway)? A frustratingly long time at a guess.
Different Word Versions
There are different versions of Word used throughout AAA. There are different
versions of Word used in the team. This causes problems and document
corruption. At some point in the future, it is expected that one writer will
use Word XP to edit a document. The differences between Word XP and Word
97/2000 are such that everyone would than need to upgrade to Word XP. Core
documentation previously used Word 97 as an authoring tool. This was causing
many problems with authoring and document corruption. Upgrading all core
writers and core documentation to Word 2000 solved all of these problems. It
is not possible to move backwards.
Each author must use the template attached to a document when maintaining that
document. Distributing templates is very bad for standards, and almost useless
when dealing with writers who do not know their tool set intimately. There is
no fixed location for templates set in Word, and different operating systems
and other tools often force the template directory to be changed on a machine
by machine basis. An example of this happens with HDK installed on Windows
2000 using Word 2000. If the username of the writer is longer than eight
characters then the template directory and startup directory must be changed on
that machine. It can be changed to anything.
The method used to overcome distributed templates is a Workgroup Templates
folder. Word will only accept one Workgroup Templates folder per
installation. This means that any writer who works in more than one group will
need to be able to make this change quickly and easily. It is not a difficult
task, but it is easy to forget. If any of the distributed writers are in
different countries, the time to open documents will be compounded by
downloading the template each time the document is open.
Templates must also be located using UNC paths, so that Word can find the
template, whereever it is on the network.
Management of a process like this is not an easy task. Because it would be a
very large change to current practises, new processes will require
development. These new processes will cost the same amount of time as
developing processes for a new tool roll out.
Standards are difficult enough to implement now, without the challenges of
having unknown authors leaving their unique brand of corporate standards
embedded through every document they touch. A simple change to standards will
require a (tele)conference with all authors before it can be implemented.
Depending on the number of authors involved, each (tele)conference will most
likely take one hour from everyone's day. 10 authors = 10 hours....
If the distributed authors are not professional writers, then things become
even harder. If development staff are used as writers, there will be almost no
adherence to standards. The current methodology requires approximately 2 weeks
to finalise the core documentation. This finalisation is simply a matter of
checking for errors. With authors who are not making a concerted effort to
follow the standards, finalisation will change from an error checking routine
to a standards implementation process. The new finalisation process would take
approximate 2-3 times longer, and would be required for every document release.
A common set of standards has yet to be developed for the entire team. While a
wide variety of document types are produced by the team, one set of standards
would be able to encompass all the documentation requirements. Whichever path
is taken to increase productivity and reduce costs, new, complete, and
encompassing standards are required.
The current core documentation has achieved a level of quality. A distributed
group of professional writers, operating under a strict standards and
management system would be able to maintian that quality. Non-professional
writers would be unable to maintain the current level of quality. The
information contained in the SAS documents is not suitable for distribution to
customers. ADC currently employs professional writers to interpret the
information presented in the SAS documents, interview the developers where the
SAS documents are unclear or incorrect, and write documentation suitable for
the designated audiences. Quality is achieved by the use of professional
authors in producing documenation for customers.
Each change made by an author will require versioning. Whatever version
control system is used will store Word documents as binary files. With the
current team being centralised, not every change needs to be versioned as it is
quite simple to ask the author what happened. To reduce the amount of
versioning required a different authoring process would be required.
Developing and managing a different authoring process takes time and money.
If development staff are to be used as writers, they would be more comfortable
with CVS as a version control system. For interacting with the professional
writing team it is possible to use the command line interface of CVS in the
same manner as the development staff, or to use one of the freely available
graphical user interfaces. Options include:
A quick web search shows many other options. IT Support would be able to
advise on the appropriate GUI to use.
Help is currently developed using HDK. A distributed authoring environment for
help development would required either a complete change of methodology, or
purchasing a copy of HDK for every author likely to work on help systems.
Purchasing a copy of HDK for all potential authors is expensive and
inefficient. Changing the current methodology is expensive to do, and the
final process would require specialised finalisation for each release. The
specialised finalisation required to work with HDK in a re-purposing mode is
extremely strict, far beyond anything ADC currently requires. The finalisation
process for help development in this case would be a minimum of three weeks per
The core team currently re-uses parts of the created content. This is done to
save time and money in developing the help system for CB. Core can achieve
these gains through thorough knowldge of the tools and systems used for
documentation. The sections of content currently re-used by core go through a
more specialised finalisation procedure than the rest of the source content.
Implementing specialised finalisation procedures on content authored by non-
professional writers is feasible, possible, and time consuming. The time taken
is related to standards and quality issues.
AuthorIT has been evaluated as a replacement system that would remove many of
the current problems associated with document production. At the same time,
AuthorIT provides for object oriented, single sourced, standards controlled
documentation, with the added benefits of increased productivity and
efficiency. AuthorIT is also designed for distributed, collaborative authoring
through the use of a database driven documentation system.
Senior Technical Writer
This mail sent through IMP: http://horde.org/imp/
ANNOUNCING ROBOHELP STUDIO
Create professional Help systems that feature interactive tutorials and
demos with all new RoboHelp Studio. More at http://www.ehelp.com/techwr-l2
Mercer University's online MS Program in Technical Communication Management:
Preparing leaders of tomorrow's technical communication organizations today.
See www.mercer.edu/mstco or write George Hayhoe at hayhoe_g -at- mercer -dot- edu -dot-
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.
- Typographical treatment of GUI components, David Chinell
- Re: [astcq-discuss] Re: Distributed authoring using Word and Domino?, Michael West
Previous by Author:
Re: Distributed authoring using Word and Domino?
Next by Author: RE: ADMIN: Civility and content
Previous by Thread: [HUMOR] Re: Hall of Technical Documentation Weirdness
Next by Thread: Re: [astcq-discuss] Re: Distributed authoring using Word and Domino?
Search our Technical Writing Archives & Magazine