Re: Formatting Chaos

[Chris Boehm <Chris -dot- Boehm -at- INEACORP -dot- COM>]

I'd call a halt immediately. Make your voice heard loud and clear
throughout the organization. You may step on some toes, and it might be
the hardest thing to do now, but imagine the frustration it will save in
the long run.

Remember, you're the expert. Reiterate that you've never seen anything
like this before, or heard of anyone who does it this way. Ask this guy
for proof-documented support that other people do projects this way, or
that this is the wave of the future. My guess is that no one is crazy
enough to have done it successfully before.
Ask the company if they really want to try something that is *so*
uncommon, at the risk of failing miserably, or do they want good
documentation.

Ask the company how they would respond if they were the customer and
received documentation like this. Maybe he needs to finish a sample
which can be tested against the normal documentation on a group of
users. After all, if they've waited this long and are willing to pay
that much money, one little beta test won't hurt, and it will also steer
you in the right direction. If he hasn't finished anything in 1 year,
also ask the company how committed they really think he is to the
documentation, the customers, and the product.

Worst case: threaten to leave, and be ready to do so. If you've made
your opinion known and feel strongly enough about it, they're bound to
listen. (Plus, you've shown results, as opposed to his non-results.)

I also think the responses you receive from this list will back you up
as to how impractical the idea is.
>----------
>From:  Dan Azlin[SMTP:dazlin -at- SHORE -dot- NET]
>Sent:  Monday, January 06, 1997 11:05 PM
>To:    TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
>Subject:       Formatting Chaos
>
>There is a problem that I am struggleing with at a client's...
>
>For the last 8 months or so I have been doing some heavy consulting hours
>with a high-tech company that is going thru some real growing pains. Their
>1.5 man writing group has been the butt of every excuse for late product
>shipments and unhappy customers. I have been able to improve this situation
>substantially, but now a new problem looms.
>
>A contract tech writer with a training background (and world view) talked
>himself into a sr techwriter position about 6 months ago. After a total of 1
>year he has not produced a single finished document for this company. He has
>spent considerable energy lobbying everyone from the Engineering VP to the
>Janitor about a grand vision he has for a centralized/modularized
>documentation scheme. When he first hit on me for support I thought he was
>going for some form of information processing... but 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 to include 6 somewhat related products ($500K-1.5M
>capital equipment) where the document is modularized as a series of
>independant monographs posing as "sections" of a comprehensive manual. 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.
>
>Now he is being forced by his manager to release a draft document for
>review. I suspect that his grand opus will crash and burn as it is basically
>unusable as currently written and structured. Suggestions that the scope be
>limited to single products and the document be structured in a more
>conventional manner have been met with some hostility.
>
>I have already picked up and repaired several projects for this client. I am
>afraid that I might wind up on the receiving end of this mess. But, more
>importantly, this client truely wants to improve their documentation
>department and I would like to help them.
>
>For one and all, your suggestions, ideas, and comments are welcomed directly
>or in public.
>
>TIA
>Dan Azlin
>Dan Azlin ** WORD ENGINEERS, Technical Writing & Publishing **
>dazlin -at- shore -dot- net                              7 Myrtle Street
>ph/fax 508-921-8908                          Beverly, MA 01915-3315
>
> 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
>

 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