ååï What are the perquisites to set up a company's documentation group from scratch

Subject: ååï What are the perquisites to set up a company's documentation group from scratch
From: "Peter Neilson" <neilson -at- windstream -dot- net>
To: "Gene Kim-Eng" <techwr -at- genek -dot- com>, Simon <wingman1985 -at- yahoo -dot- com -dot- cn>
Date: Tue, 16 Jul 2013 05:46:25 -0400

On Tue, 16 Jul 2013 02:41:12 -0400, Simon <wingman1985 -at- yahoo -dot- com -dot- cn> wrote:

The docs are there (written by disgruntled engineers). However, the accuracy and relevance as well as compliance is very poor. No dedicated resources are provided for this effort.

I fear that you will find yourself shoveling sand against the tide. Here, in my usually jaundiced view, are a few of the many problems you will face.

1. There will be resistance to providing good reviews, as we discussed earlier.
2. Some reviews might consist of reversion of the document to exactly as it was before you made any changes.
3. Reviewers might attempt to correct use of language but carefully avoid the seething technical issues.
4. You'll be unable to assemble criteria by which you can know that any part of the documentation effort is complete.
5. You'll be unable to discover the identity of the intended audience.
6. You'll discover that a rough draft has been shipped as if it were a completed document.
7. Some of the original documentation that you'll be handed (as starting material) will turn out to be copied directly from competitors' literature or from Wikipedia. (Google for unique phrases. You might be amazed!)
8. Your very best SME will suddenly be reassigned to a different project, elsewhere, leaving your doc project in limbo.
9. You will find that your polished English-language effort has been translated into Chinese (for top-level review) and then back to almost-English before being sent to customers.
10. You will lose effectiveness because you are seen as too pushy.
11. You will discover that you have been unable to spend enough time doing actual documentation because you got subverted into helping friends learn English.
12. As you add other writers to your doc group, you will encounter all the standard problems of managing them. "Herding cats" is the usual metaphor. Try to develop performance criteria as well as standards.

I'm not saying that the task is impossible, but that you'll need flexible plans that can handle problems that suddenly arise from nowhere. And yes, having some sort of method for tracking the changes to your documents will be very important. In particular you must avoid a losing control of your "master" copy of each document. Something like SVN can let you rewind to a previous version and undo misapplied changes.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more: http://bit.ly/ZeOZeQ

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

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

References:
What are the perquisites to set up a company's documentation group from scratch: From: Simon
Re: What are the perquisites to set up a company's documentation group from scratch: From: Gene Kim-Eng
ååï What are the perquisites to set up a company's documentation group from scratch: From: Simon

Previous by Author: Re: Why is so hard to for majority Chinese companies to take documentation seriously?
Next by Author: Re: Comma question
Previous by Thread: ååï What are the perquisites to set up a company's documentation group from scratch
Next by Thread: Re: ååï What are the perquisites to set up a company's documentation group from scratch


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads