Re: Formatting Chaos (longish)

[Rebecca Phillips <Rebecca -at- QRONUS -dot- CO -dot- IL>]

>
>
>>> A contract tech writer with a training background (and world view) talked
>>> himself into a sr techwriter position about 6 months ago.<snip>  it soon
>>>became apparent
>>> that he didn't know what he was talking about.  He has been able to obtain
>> >defacto approval (i.e. he hasn't been told NO) to create a single massive
>>> maintenance document <snip> There
>>> is no uniform section numbering, page numbering, figure or table
>>>labelling,
>>> single TOC or index. Figures are simple "there" with no contextual
>> references or identifying labels/numbers. He has also spent weeks
distilling
>>procedural and theoretical descriptions to their "minimum requirements,"
>>sometimes distilling several pages of source material from previous manuals
>>into a single sentence. <more snip>

Dan:

Firstly, the problem is taking on the monumental mess that someone has
had six months to make, and your being in the position of trying to undo
it in less than six months. However, beyond time constraints, I believe
your problem has three facets:

1. Practical formatting.
2. Repairing descriptions and procedures which have been "distilled"
beyond recognition.
3. Documentation definition and organization.
4. Politics

1. Regarding practical formatting, you haven't mentioned what software
the documentation was written on. What you need is some kind of "macro
suite" which contains automated routines for standardizing formats,
captions, headers and footers. If you are not one yourself, you should
find a consultant who can help you produce this kind of formatting
suite. (I know someone who does this for Word, if you are interested.
For Frame I think you can do this only in a UNIX environment.)

2. Repairing mangled descriptions has no quick fix. You can go back to
the original procedures and ditch all the work this consultant has done.
You can try to repair the damage he has done by re-re-writing the stuff.
Fixing this is equivalent to writing a new document. You have to budget
time and money accordingly.

3. The basic problem with the document is its organization. You have
described the document as useless. Why do you want to repair it? It
sounds like it just needs to be put to sleep. From what you have
described, you have to start from scratch if you want to end up with
something useful. Hopefully you can think of some tactful way to say
this to the management. It doesn't sound like there is any way of saving
this document in the short term.

4. Politics. You used the passive voice when you said that suggestions
to produce a more conventional document were greeted with hostility.
Therefore I do not know whether the management is hostile or the sr
writer is hostile. In either case, I wouldn't worry. Try your best to
ostracize yourself from the monster document until it is presented to
the manager. MAKE SURE the manager knows you were involved only
minimally, BEFORE it is presented. When it falls flat, the management
will probably conclude it was a bad idea, both to produce the document,
and to hire this guy as a sr tech writer.

Rebecca


Rebecca M. Phillips
Documentation Manager
Qronus Interactive Ltd.
Automated System Testing
http://www.qronus-int.com
rebecca -at- qronus -dot- co -dot- il





>

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html