Fwd: [astcq-discuss] Re: Distributed authoring using Word and Domino?

[geoff -at- userdox -dot- com]

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.


Hi Xxxxxxxx,

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 
more time.


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.


Purely Technical

Images
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.

Version Control
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 
this issue.
If versioning is not required, but check-in/check-out is required, Domino or 
CVS are both suitable tools.

Standards
It is not possible to implement standards in a distributed environment of non-
professional writers.  It is difficult, but possible, to do so with 
professional authors.

Single Sourcing
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.

Templates
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

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

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.


Quality

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.


Version Control

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:
gCVS (http://www.cvshome.org/dev/addons.html)
LinCVS (http://www.lincvs.org/)
SmartCVS (http://www.smartcvs.com/)
TortoiseCVS (http://www.tortoisecvs.org/)
CvsGui (http://www.wincvs.org/)
A quick web search shows many other options.  IT Support would be able to 
advise on the appropriate GUI to use.


Help Development

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 
help system.


Re-using Content

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.


Other Alternatives

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.


Regards,

Geoff Purchase
Senior Technical Writer


[snipped]



-------------------------------------------------
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.