Documentation planning (was Re: FW: Extreme Technical Writing)

[SIANNON -at- VISUS -dot- JNJ -dot- com]

Ymorrigu writes (among other things):
>   1. Basic working model is developed along with basic documentation 
>   structure.  This includes an overview all existing modules and 
>   components, and documentation for all existing functionality.

You know, I am *still* surprised at how often this step gets ignored, even 
in "traditional" development methodologies. (I know, give me a few more 
years and the surprise will pass...)

I know many of you are working in team environments with solid processes, 
so let me say up front that this question will probably not apply to you.

For those of you who have been called upon to bring order out of chaos, who 
have inherited a diverse stack of miscellaneous documentation to go with a 
project that has been insufficiently or ineffectively documented before, 
who have been brought in on a project where there was *no* communications 
plan and scanty or absent documentation standards (and for which you are 
often the lone tech writer):  How have you approached establishing a 
documentation structure? What tips and tricks have you amassed over the 
years that you'd be willing to share? Have you developed an "archetype" 
structure to bring with you if/when you move to another job?

I think this "organizational" phase is the most often undervalued yet vital 
segment of the job; I've run across a couple situations where lone 
techwriters I've met have been given *no* guidance or direction about the 
doc set needed for the projects they work with, and invariably they find 
themselves having difficulty with scope, depth and prioritization of their 
docs.

(I know I've developed a philosophical "map" from which to determine the 
"landscaping" needed for a specific project, but mine won't necessarily 
work for someone else, and every approach to a concept gives a new 
opportunity.)

Just stirring the stone soup of discussion,
Shauna
--------------------------------------
>From Dilbert's Top Twenty Fun Things to Tell Programmers:
16. Although the module is mathematically correct, the solution is 
physically impossible. Either that, or you have actually created mass, and 
I will apologize for underestimating your power.
- just call me bert

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Attention ForeHelp and Doc-to-Help Users! Upgrade your existing product to 
RoboHelp for FREE, through January 15th. RoboHelp can import your existing 
Help projects! Learn how else RoboHelp can benefit you. www.ehelp.com/techwr

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