Re: the way it's supposed to work

[Andrew Plato <gilliankitty -at- yahoo -dot- com>]

> > Dunno about that.  More than once I've been told to
> > document the way it was
> > supposed to work, not the warts-and-all mess they're
> > shipping out the door.
> 
> Not just the doc side, but I make a good chunk of my
> living explaining how things *should* be. Half my
> working hours are spent in meeting rooms and in
> hallway conversations about change, and how to manage
> that change.

Let's clarify.

1. Development documentation:  This where you are documenting the development
of a new something. In this case, you're often explaining things that will
exist or are planned to exist a certain way.

2. Operational documentation:  This is where you document the way things ARE.
This may serve many purposes, such as auditing or just to fulfill a
requirement. 

3. Results / Report Documentation: This is where you are digesting the
information gathered from some process and reporting it to an audience. 

Development documentation is not the same as operational or report style
documentation. In a development environment, its natural to document things as
"the way they should be." In an operational/report environment, you document
things the way they ARE. 

Generally, if a process is in place and being used, and somebody says "document
that." they mean, "document it as it is right now. Don't editorialize about it
and don't try to force it to meet your personal agenda." 

Furthermore, its important to note that writers do not just get handed
authority to participate in the design process the moment they walk in the
door. A writer usually must demonstrate their value to the team and a profound
understanding of the subject matter before they are allowed to have an active
role in the design and development processes. 

The original poster to this thread, was complaining about what a ludicrous
process was used at his/her employer. However, it sounded like this person
wanted to use the documentation process as a mechanism to redefine the process.
That is likely not the purpose of such a process nor may it be in scope. The
writer was assuming a responsibility he/she may not have. That's a risky
venture. Assuming responsibilities that are not intended for your job
represents risk. This is why its important to establish expectations and job
responsibilities with management. Know your limitations and how to properly
exceed them. 

As for ISO and all that quality improvement crap, most of that is total BS. It
makes people feel better about their ad hoc ways. Ludicrous processes are part
of the corporate landscape. Its why process, in general, is kind of like a
weapon of mass destruction. Processes in and of themselves are neither good or
bad. Its how they are used that can cause widespread disaster. But that's a
different philosophical quagmire for a different thread.

Now, get the hell back to work, you. 

Andrew Plato 

__________________________________
Do you Yahoo!?
Exclusive Video Premiere - Britney Spears
http://launch.yahoo.com/promos/britneyspears/

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

ROBOHELP FOR FRAMEMAKER TRIAL NOW AVAILABLE!

RoboHelp for FrameMaker is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to online Help, intranet, and Web.  
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! Call 800-718-4407 for 
competitive pricing or download a trial at: http://www.ehelp.com/techwr-l4

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