Re: Documentation Correctness was Re: How many levels of indentsandheads are reasonable?

["Gene Kim-Eng" <techwr -at- genek -dot- com>]

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