Re: What Are Writing Skills?

[Tony Markos <ajmarkos -at- yahoo -dot- com>]

--- David Neeley <dbneeley -at- gmail -dot- com> wrote:

Tony,

I continue to be amazed at the ongoing examples of
hubris in this thread.
 
Your assumption that skill at engineering and skill
 at documentation are necessarily co-existent in the
same individuals flies in the face of the experience
of *many* people, both on and off this list.

Tony Markos responds:

David Neeley:

Please don't confuse good engineering with what most
engineers do.  Most software engineers are unskilled
at engineering - at least from a true DFDr's
perspective. And just like they can only apply
blue-collar technqiues at product design, they can
only apply blue-collar techniques at documentation
design.

What I am saying is this:  If an engineer produces
quality product design work, and if he/she is like
motivated to produce quality in all his/her other
deliverables, his/her mindset will not change between
deliverables; he/she will not mysteriously transform
from being a "brilliant engineer" to being a
documentation "hack".  

David Neely:

Next, your continued assertion that there should be
some sort of simple-to-manage guideline for
"structured writing" again seems more than a little
disingenuous.

Tony Markos:

If structured writing is as fundamental (i.e., common)
to tech writing as I have been told, then discovering
specific, concrete steps and/or techniques should be a
very straight forward exercise.  It is not; I suspect
that structured writing is nothing more than poor
man's analysis (user and product).

David Neeley

What I *think* you are referring to [regarding
structured writing] instead is in the arena of
document organization. 

Tony Markos:

Yes, when I was told that structured writing is the
"meat (my word) of TWing, this is what they meant.

David Neeley:
 
You contend that there "should" be a process for
creating well-arranged documents that would be a sort
of "paint-by-numbers" recipe for preparing or
analyzing a well-built document...similar to
the dataflow diagrams you are so passionate about.

Where you fail in your quest, I believe, is your
misunderstanding that a human language is far more
complex than a software language. We are immersed in
language throughout our lives, and we absorb much of
what we "know" about it without conscious thought.

Tony Markos:

If you are saying that Technical Writing is so complex
and mysterious that there are no concrete, specific
steps and/or techniques for it, I say nuts.

David Neeley:

Principles of writing effectively are thus composed
of learned skills of two essential kinds--the ones
that are explicitly taught or studied, and the ones we
have absorbed through our prior experience.

Tony Markos:

Right, like everything else.

David Neeley: 

Because engineers quite often have little clue as to
the business needs of the customers. There is such a
common disconnect between the users and the software
engineer that many software products are built that do
not reflect the actual real-world concerns
of users. 

Tony Markos:

Right, most engineers (and TWs for that matter) are
poor at the essentials.  Whats new?

David Neeley:

The Software Quality Institute has estimated that
*billions* of dollars in software development are
wasted, in fact, each year.
 
Tell me, please: does this mean that there are so few
truly competent engineers?

Tony Markos responds:

In engineering, as in life in general, only two
percent of the people are problem solvers - the rest
are just along for the ride.  One man with DFDs can
run circles around a small army of competing engineers
without them!

David Neeley:

..In addition, it is also very common for various
development engineers to have little clue as to the
scope of the requirements. Usually, the project
manager has the responsibility for this view of the
target; individual developers are generally assigned
to one facet of the problem at a time.

Tony Markos:

Even the Object Oriented Analysis community (post lost
souls) acknowlege that only Data Flow Diagrams provide
a rigorous technqiue for defining scope.

David Neeley:

Thorough understanding of an application can still
produce very pedestrian documentation, while someone
with a lesser understanding of the application may
produce a brilliantly-conceived user guide to the same
application stemming from knowing "just enough" about
it to suit the needs of the audience.

Tony Markos:

You don't have to know everything - but it is critical
to know the essential.  That's what the strong suite
of a true Data Flow Diagramer: A focus on the
essential like a laser!  

David Neeley:

I would submit, too, that in extremely complex cases
far too much time would be consumed in gaining a
complete understanding if the objective  is only to
document a part of the app. For example, I was doing a
little research this morning about VistA, the
medical records suite developed by and for the
Veterans Administration.....

Tony Markos responds:

VistaA, Veterans Admin..  Ding, Ding, Ding, (sound of
my mind tying thing together),  I think we may have
worked together briefly at the Brecksville Ohio VA. 
As you are who I remember, then surely you are aware
of the need for formal scope definition and a rigorous
big picture!



		
__________________________________ 
Do you Yahoo!? 
Make Yahoo! your home page 
http://www.yahoo.com/r/hs

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

WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:
http://www.webworks.com/techwr-l

Your Ad Here! Have a product or service you'd like to get some attention for? Use this space to get the word out! Contact lisa -at- techwr-l -dot- com for more details.

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.