RE: Documentation Correctness was Re: How many levels ofindentsandheads are reasonable?

["Butler, Darren J Ctr 584 CBSS/GBHAC" <Darren -dot- Butler -dot- ctr -at- Robins -dot- af -dot- mil>]

Gene Kim-Eng stated: The best discussion the "TW acedemic or industry
communities" can have on this subject is to help writers learn how to
identify companies with such development processes in time to avoid
joining them in the first place. 

 

Would it be fair to say that a company's TW department has some level of
responsibility in (at least attempting to) point out any short-comings
and errors of the developmental process? The TWs may be the only "canary
in the coal mine" to alert that things are going horrible wrong -- just
before we pass out.

 

I guess it all depends on whether or not the documentation is parallel
to product development or an after - (w-a-a--y after) - thought.

 

Have any of you successfully fostered process-change?

 

Blessings,

Darren

****************************************

Darren J. Butler

Sr. Technical Writer-Editor, Template Wrangler, Mil-Spec Pharisee

Integrated Data for Maintenance

NG Corp

 

-----Original Message-----
From:
techwr-l-bounces+darren -dot- butler -dot- ctr=robins -dot- af -dot- mil -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+darren -dot- butler -dot- ctr=robins -dot- af -dot- mil -at- lists -dot- techwr-l -dot- 
com] On Behalf Of Gene Kim-Eng
Sent: Wednesday, October 17, 2007 10:43 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Documentation Correctness was Re: How many levels
ofindentsandheads are reasonable?

 

Offhand, I would say that most people in the TW field understand,

instinctively if not explicitly, that if a "rigorous analysis" has not

been conducted to identify "the essential tasks to be performed"

and "the interrelationships between the tasks" by the developers

before development reaches a stage where there's anything to

write about, then the product or system being developed is going

to be inherently "disjointed and incomplete" (in other words, bad),

documenting it six ways to Sunday will not correct its basic

conceptual and design faults, and the document team's energies

will probably be better spent polishing up their resumes and

interviewing skills and looking for their next jobs or contracts

instead of trying to become substitute project managers and

engineers.

 

"Successful" and "quality" documentation doesn't turn a product

whose development process is bad into a good product, it just

makes it easier for readers to quickly realize that the product is

bad.  The best discussion the "TW acedemic or industry

communities" can have on this subject is to help writers learn

how to identify companies with such development processes

in time to avoid joining them in the first place.

 

Gene Kim-Eng

 

 

 

----- Original Message ----- 

From: "Richard Lewis" <tech44writer -at- yahoo -dot- com>

>I spend alot of my time creating data flow diagrams to tie together
disjointed and incomplete requriements and tech specs.  I am by 

>no means perfect, however, the difference before and after is usually
profound.

> 

>  But think about it:  I am stating that nobody in the TW acedemic or
industry communities knows about or is willing to admit to 

> what is key to success in creating quality docs - especially for
larger scale systems.  Ya have to admit to it, either I am right 

> and the world is wrong, or vice versa.

 

 

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

 

Create HTML or Microsoft Word content and convert to Help file formats
or 

printed documentation. Features include support for Windows Vista & 2007


Microsoft Office, team authoring, plus more.

http://www.DocToHelp.com/TechwrlList

 

True single source, conditional content, PDF export, modular help.

Help & Manual is the most powerful authoring tool for technical

documentation. Boost your productivity! http://www.helpandmanual.com

 

---

You are currently subscribed to TECHWR-L as
Darren -dot- Butler -dot- ctr -at- robins -dot- af -dot- mil -dot- 

 

To unsubscribe send a blank email to 

techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com

or visit
http://lists.techwr-l.com/mailman/options/techwr-l/darren.butler.ctr%40r
obins.af.mil

 

 

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

 

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit

http://www.techwr-l.com/ for more resources and info.

 

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

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
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-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

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