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

Subject: RE: Documentation Correctness was Re: How many levels ofindentsandheads are reasonable?
From: "Butler, Darren J Ctr 584 CBSS/GBHAC" <Darren -dot- Butler -dot- ctr -at- Robins -dot- af -dot- mil>
To: "Gene Kim-Eng" <techwr -at- genek -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 17 Oct 2007 12:30:45 -0400

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.


Follow-Ups:

References:
RE: Documentation Correctness was Re: How many levels of indents andheads are reasonable?: From: Richard Lewis
Re: Documentation Correctness was Re: How many levels of indentsandheads are reasonable?: From: Gene Kim-Eng

Previous by Author: RE: once or twice...
Next by Author: RE: Referring to the name of a system (aka FrameMaker Variables vs. Conditional Text)
Previous by Thread: Re: Documentation Correctness was Re: How many levels of indentsandheads are reasonable?
Next by Thread: Re: Documentation Correctness was Re: How many levels ofindentsandheads are reasonable?


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


Sponsored Ads