Re: What Are Writing Skills?

Subject: Re: What Are Writing Skills?
From: Dick Margulis <margulisd -at- comcast -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sat, 12 Mar 2005 16:36:32 -0500

Tony Markos wrote:

Sharon Burton:

I think I sent you a small reading list.
Tony Markos:

If you did, and I really don't remember seeing such;
if the readings give specific, concrete technqiues
and/or techniques PLEASE resend - I really seek an
answer to "What Are Writing Skills?"

Dick Margulis interjects:

Tony, perhaps your difficulty in understanding the concepts that have been laid out for you stems from a lack of reading skills. It seems to me that Sharon and others (myself included) have, with great patience and forebearance, answered your questions in some detail. Yet you persist in standing there with your eyes closed tight and your fingers in your ears, shouting, "la-la-la-la-la-la-la-la-la-la-la-la-la-la I can't hear you," the whole while and then blaming us for not answering you.

Let me be clear about this: We do understand the importance of DFDs, even if not everyone places as high a value on them as you do. We also use other tools, because we have found that DFDs alone do not completely describe the content and structure of effective documents. You can learn about these other tools (not by Googling on perversely vague keywords but rather by reading actual books and taking actual courses) if you will only open your mind to the possibility that you don't already know everything there is to know.

Sharon Burton:

I offered to let you take my class this spring where I
can teach you how to write in a structured way.

Tony Markos:

Thanks for the offer, but if structured writing is so
fundamental to TWing, to answer my basic question, I
really should not have to go to such lengths.

Dick Margulis interjects:

Why not? Writing a good document is somewhat more complicated than, say, washing your hands. Why shouldn't you have to go to some lengths to study the subject before making such sweeping generalizations about it?

Dick Margulis offers a concrete example of structured documentation:

Tony, some years ago I worked on a project team that designed a complicated piece of medical equipment. The machine had several modules, each of which required cooperation among mechanical, electrical, and software engineers. The modules interfaced with each other and with the outside environment, as well.

There were several possible ways to organize the design specification for the machine. There were, in fact, several possible ways to conceptualize the hierarchy of the system. We could have had a document on the electrical subsystem, another on the fluidics subsystem, another for the mechanical subsystem, another on the software subsystem. And in each of those documents we could have discussed the fourteen modules. That was one approach we considered. We could have organized the documents according to the bill of materials. In the end we decided that creating a design document for each module, although it would require more total signatures from engineers to do so, would result in a document that would be more intuitive and transparent to outsiders reviewing the design (future project teams leveraging the design for a more advanced product, manufacturing and service engineers trying to get a handle on how they should work with the machine, regulators inspecting the quality system, etc.). So that was the structure we chose for the documents.

The team that created the user manual for the machine took an entirely different approach. They listed the user interfaces (ports for introducing various supplies and test substances; various input and output screens; controls and adjustments) and proceeded to instruct users in how accomplish their six or seven basic types of tasks by interacting with those various interfaces.

As I suggested in an earlier post in this thread, the structure of the machine in n-space was invariant; but each document was a projection in, perhaps, two-space of that structure, in such a way as to preserve all important information in each document.

Now you can continue claiming that you don't understand what I'm saying, but please stop claiming that I haven't said it.


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: Procedures for a young writer
Next by Author: Re: What Are Writing Skills?
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