Re: What Are Writing Skills?

[David Neeley <dbneeley -at- gmail -dot- com>]

Tony,

It is always refreshing to observe that some things in life never
change...such as your devotion to bringing data flow diagrams into
nearly any context as your own personal "holy grail."

If you understand how to thoroughly analyze a system, that is but the
first step. Communicating *enough* understanding to be useful for any
given audience is a second step that is no less significant.

It is like the old saw that "...he's the sort of fellow who instead of
telling you the time wants to tell you how to build the watch!" It is
not always appropriate to attempt to tell all you know about a
system...many times, what you leave out may be as important to
usability as what you put in.

As for grammar knowledge--it would help, I think, if you did not tend
to restate the obvious quite so often. I think we can agree that the
ability to write simply and clearly is important to tech writing--not
the ability to parse the most convoluted of sentences. Since such
simple writing is relatively common among eighth graders, that does
not mean that it is unimportant to adults as well.

You asked what is involved in "structuring information." As is so
often the case, let us see a protracted example of what it is not.

Over a rather frequent series of posts here, you seem to have not yet
found the ability to structure your argument about dataflow diagrams
in a manner that would lead to a more universal understanding and
acceptance of your point of view. It has been said that the true
definition of insanity is to keep doing over and over the same thing
in the quest for a different result.

It seems to me, then, that the goal of true writing clarity on this
subject is still an elusive one for you...and the fact that you seem
to disparage linguistic facility among writers begins to take on a
rather ironic aspect.

It is quite true that there are indeed many people who have "received
a B" in basic composition courses and who *might* be able to do the
writing part well enough. However, it is also true that there is a
lamentably high percentage of people who hold themselves out as
"technical writers" who produce purely pedestrian work. If, therefore,
you are advocating for such pedestrian work, then I think few would
argue with you that relatively pedestrian skills are all that is
required to produce it.

On the other hand, the skill of marshaling information in a logical
manner that meets the needs of the audience--that is persuasive in
helping "sell" the needed information; that is clear and concise; and
that includes what is needed *and little or nothing else* in an
arrangement that makes it most accessible to the user...that is all
part of what seems to me to be "information structuring" that is basic
but essential to technical writers.

If I understand your position and attempted to "sell" it to this
audience, I would take a little different tack than you have adopted.
Let us use this, then, as a suggested positing of your argument that
seems to be somewhat more effective than the querulous tone you seem
to prefer:

First, I would suggest that we should be able to agree that in doing
documentation for complex systems, it is extremely important to come
to a high-level understanding ourselves. I doubt there are any here
who would disagree with that.

Next, I would observe that a method of "shorthand" to represent the
system and its interrelationships is to diagram it using the dataflow
approach. Further, I would point out that this is a method that can
speed our own understanding, for the various system architects or
other SMEs can quickly identify any misperceptions we may have as we
try to come to grips with it ourselves. Thus, using the diagrams can
be a much faster method of reaching understanding and agreement.

At this point, I would point out that this diagram now can be both a
reference for our writing (to make sure we don't begin to run astray
and to be sure that we are neglecting nothing of significance) and
also a part of the finished documentation for those who find this
resource helpful in their own understanding.

Finally, I would use a few anecdotes showing how the diagrams have
proved superior to other approaches.

Since each stage of this argument seeks both understanding and
agreement, it is far less likely to gain opposition among those who
may not buy the sort of bald propositions with which you have often
greeted the discussion. It also avoids the "either/or" kind of
discussion in which you seem to strive for the impossible goal of
cramming this one technique down the throat of everyone else even if
they do not understand its best application and, too, its limitations.

Then, you would also be in the position of being able to evaluate
*other* aspects of the tech writing challenges that are *not* related
to the analysis phase. For example, learning to (here it comes!)
*structure information* so that what you are seeking to impart is both
effective and maximally useful to the target audience.

In my opinion, there are a number of different tools in the arsenal of
a professional technical communicator--each important in its own way
and nothing used to the exclusion of the others. Data analysis
techniques are only one of those tools. As each of us identifies those
tools we need to acquire or upgrade, we improve in the associated
area. Neglecting any of them, though, can only be done at the peril of
the best possible work product. It matters little how much you
understand the subject matter if you are not sufficiently proficient
in identifying that part which the audience needs and can accept.

Skill in argumentation, including information structuring, is equally
essential to data analysis in our repertoire...and for data analysis,
dataflow diagramming is only one technique and it may or may not match
the needs of a given individual since some think quite differently
than others.

Finally, your question: "How is the structuring of information for
presentation different than obtaining a properly structured
understanding of the product AND the user."

Tony, I hope that the above example has given you some indication that
may help answer your question. However, I think I should observe that
you seem to be in the dark about the other tools needed. Yes, a
"properly structured understanding of the product" is certainly
useful. A "properly structured understanding" of the user is likewise
important. You left out the medium you will employ to impart a
necessary understanding *to* the user. If I understood the original
comment, a *presentation* (can we all say "PowerPoint"?) is quite
different, say, than a reference manual; both are different from an
instructional manual or a user manual; and all are different than an
online help system. Each has its own abilities to present information;
each has its own limitations. Thus, the information content and the
presentation of same varies as well.

Surely this was part of "tech writing 101" for you?

David

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

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

Doc-To-Help 7.5 Professional: New version with new features, improved performance and reliability, plus much more!  Download your free trial today at www.componentone.com/techwrlfeb.

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