RE: When you need to restructure

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

Hi Jane,

I agree with John Cornellier's approach.

Even if the existing structure is poor, I don't think that it is wise to
throw out the existing content and start writing from scratch.

You said yourself that you have only been on the job two weeks. If you
re-write from scratch, a couple other disadvantages is that the
documentation might reflect your inexperience with the project and the users
lose that information.

You mention that you have a new template. I recommend that you make your
first pass at just changing from the existing template to your template.
Don't worry about content in the first pass except to become familiar with
it. Tools like FrameScript and SuperWebbundle for FrameMaker can make this
an easy one day job.

In pass two, take everything apart and try to organize what exists in a more
logical fashion (such as John's approach).

Pass three, fill in the holes and transitions with freshly minted text.

Pass four, re-write things that annoy you from the original.

As John points out, you can re-organize an existing manual much quicker than
you can write it from scratch. The organization might be the stumbling block
and not the actual text.

Divide and conquer.

I think that you should take advantage of the existing "long, densely
informative but unstructured sentences that my predecessor wrote." If it's
not wrong, don't try to fix it NOW. Consider it a political move. More
important than that, every where I have ever worked, I could not afford to
throw away the efforts of my predecessors all at once. Piece-by-piece over
time, but not all at once.

You'll be able to make your delivery date easier, because
push-comes-to-shove you can stop after you get the structure in place. The
following release will tackle the edits to the predecessor's work. To those
who complain, "it was written that way in the last release."

======

At my last employer -- an Austrian company with non-native English speakers
writing in English --, it was certainly a challenge living with the stilted
text. Due to translation issues, I was forbidden from changing things at the
sentence level, because that would trigger translation work in too many
languages. (Why'd they hire me if they weren't going to use all my skills?)
I would have made an even bigger issue of it (over and above the complaints
of the translators) if it weren't for the fact the organization of
everything else was all screwed up.

Someone wasn't paying attention when using an older Version of ForeHelp. All
topics were placed in alphabetical order; the few browse sequences that
existed were seriously hosed; the TOC's were incomplete and inadequate;
inefficient use of SourceSafe and project files made for massive
duplication.

I got buy-off to do the restructuring, providing I didn't go below the
sentence level. (There were times when I did anyway.) I went through each
and every topic,  put it in a new, logical order, created comprehensive
TOC's, etc. This allowed me to find duplication and to consolodate. I got it
positioned so that my successors could then methodically target a module at
a time going below the sentence level.

This two pass approached (my restructuring followed by editing) offered two
immediate advantages. I could concentrate on the big picture and how a user
would need to see the material. My seccessors got context to aid in
understanding the material in order to be able to perform the correct change
below the sentence level.

Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com



> -----Original Message-----
> From: bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com
> [mailto:bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com]On Behalf Of Jane
> Carnall
> Sent: Monday, April 30, 2001 8:49 AM
> To: TECHWR-L
> Subject: When you need to restructure
>
>
> I've just had a really productive meeting with a couple of designers
> (internal customers for the documentation set) and have come to the
> conclusion that the documentation set pretty much needs some terrific
> restructuring. Since the content also needs some considerable
> rewriting, I'm going to just start fresh from brand-new templates, rather
than
> doing a lot of copying, cutting, and pasting.
>
> The advantages are: (1) I've only been on the job two weeks, I
> have nothing to lose by re-starting
> (2) I don't risk getting content in two places at
> once (3) I make sure the documents are all up-to-date with the most recent
> version of the template (4) I can quickly set up skeleton versions of what
> the manuals ought to be.
>
> Disadvantages: (1) For a while, it's going look like I not only
> haven't done
> anything, I've actually gone backwards. (2) I won't be able to take
> advantage of all the long, densely informative but unstructured sentences
> that my predecessor wrote (this isn't really a disadvantage) (3) Er, can't
> think of any other disadvantages: well, except that my
> predecessor is still working here and did put in a lot of work and
> I don't want to imply that it was all worthless, because it wasn't: it
just
> doesn't seem to be exactly what's needed.
>
> What do other people do when a project's documentation needs a complete
> rework? How avoid treading on people's toes?


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems 
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East, 
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline 
April 27. http://www.pdfconference.com. 

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