Re: What Are Writing Skills?

Subject: Re: What Are Writing Skills?
From: David Neeley <dbneeley -at- gmail -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sat, 12 Mar 2005 13:55:28 -0600


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.

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.

I should remark that you appear to be mislabeling what you seek.
"Structured writing" is a term of art referring to the preparation of
structured documents, generally ones using a tagging language such as
XML or SGML. In fact, there is a large organization devoted to this
technology: .

What I *think* you are referring to instead is in the arena of
document organization. This is a horse of a considerably different
color, as it happens.

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.

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.

There are, in fact, courses and books devoted to creation of various
kinds of documents. This is why I referred to being disingenuous

As for the touted ability of an engineer to discern "...up to
ninety-eight percent (98%), of the required work is comming [sic] up
with a comprehensive, integrated understanding of the end-user's goals
and tasks and how all of those goals/tasks interrelate" -- I contend
that this is often relatively impossible.

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

In fact, it is also common in my experience to find that users are
often quite unaware that what they think they want and what they might
need to work more effectively in accomplishing their organization's
goals are often very different. Users also have little idea of what
they can ask for from software.

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.

You focus on the analysis part of the task. I concur that in an ideal
situation, a rigorous analysis of the application is extremely
helpful...but not at all all-encompassing. Someone who has the most
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.

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. That suite contains
about a hundred separate components, which can be combined in nearly
endless combinations depending upon the needs of the facility
involved. While it would be helpful to have a complete dataflow
diagram of the whole thing, if my task were to document only those
modules to be installed at a given facility I would find much of the
rest of the information to be purely excessive to my needs...and I
could not in good conscience take the time to learn about the
functionality of other, nonused modules.

Extending this example--let us say my task was to create a user guide
for a single module in that stack...again, I would not be able to take
the time to learn more about the whole thing than I might need for the
single module. That would be cheating the customer.

Personally, *before* I begin an analysis of a given application, I
begin with a thorough study of the requirements documents and do any
study I need to understand not simply the given requirements, but how
the end product is expected to solve the users' problems.

Because I have fairly broad experience in business management
consulting, I approach the problem from a different perspective than
the engineer. My major task is to solve a customers' problems--as,
indeed, it should be for the software developer. (This is also why it
is a very good idea to involve competent tech writers early in the
process, during the development of the requirements, rather than
waiting until much later!).

One result of this process is to begin to rough out an outline for the
deliverables--reflecting the user requirements and problems in an
organized fashion.

With this background understanding, I then begin the analysis of the
software product. I am seeking to understand from the perspective of
the requirements how the application fits. I often don't need to
develop a deep, expert-level understanding of the internal workings of
the application if my only charge is to do end-user documents, for

During the analysis phase, since I have previously come to understand
the user requirements, I make notes of capabilities that are used for
the various user tasks. This saves a great deal of time later as it
comes to planning the document deliverables. Generally, I fit these
notes into the outline I have prepared already...looking all the while
to see if the outline needs to be modified in some way to be more
effective. Using the outline, too, I make sure that I have overlooked
nothing in the analysis.

Note, please, that the original outline is in itself a basic document
plan. It is already structured logically, and will usually consist of
sections for each deliverable.

Thus, by the time I am thoroughly familiar with the application I have
already a good skeleton to build the docs on.

Of course, in the real world, much of this is done in a much more
piece-meal fashion because it is usually happening during the process
of development. Since I usually get only a partial functionality at a
time, I work on the relevant portion of the outline as I go...and each
time there are programmatic changes, I revisit the relevant sections
to update correspondingly.

Because I have a firm understanding of what the application is trying
to accomplish, if the application as it is being developed is missing
something or if it is departing from the requirements, that puts me in
an ideal situation to take any concerns that develop to the project
manager. In addition, things that don't work as they should result in
notes to the QA folks and the developers.

The result, then, seems to me to be a fairly workable methodology that
respects the development process and results in a logical document

However, I am also a firm believer in getting all the user feedback
possible to refine the documentation to be the most effective resource
we can make it within the time and budget constraints we operate
under. If the docs are designed with a modular approach, it is fairly
easy to restructure them as needed.

In sum, then, I would offer these suggestions:
1) Any more analysis than what is "enough" is a waste of time
and resources.
2) A workable structure for the deliverables should come from a
preliminary understanding of the requirements...what user problems the
application is intended to solve, and often is put in place *before*
the analysis of the application itself.
3) There is no single method for arrangement or structuring
deliverables. The end result should instead reflect the needs of the



Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:

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 for more resources and info.


RE: What Are Writing Skills?: From: Tony Markos

Previous by Author: Re: documentation plans - allocating time
Next by Author: Re: Looking for totally subjective opinions on HATs
Previous by Thread: RE: What Are Writing Skills?
Next by Thread: Re: What Are Writing Skills?

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

Sponsored Ads