TechWhirl Sponsors

About TechWhirl

TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.

For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.

>
>Dick, how would you know that the organization of your document was
>effective? How would know that your audience's needs were fulfilled?
>

Ahh, Phil, now we're getting to the crux of the issue.

In your model (Process! Process!--apologies to Little Caesar) documents are tested with a statistically sampled audience, and statistics are gathered and analyzed. On average, we learn, sentences should have no more than eight words and paragraphs should be no longer than three sentences. Etc. (I just made up these numbers for illustrative purposes. Please, nobody take them as meaning anything.) Those are metrics we can apply to evaluate a draft or a release candidate and thereby arrive at a quality rating.. If the rating is high enough, the document must be good enough. A monkey at a keyboard can write a document that will get a high score, but you know as well as I do that this is meaningless.

So how do we distinguish between the good document that gets a high score and the monkey-generated document that gets a high score? We can infinitely regress the statistical analysis, but we will get increasingly meaningless statistics. Further, if we apply these statistics as metrics for new documents we will reject an infinite number of perfectly good documents that happen to differ in some insignificant respect (but one that is measured nonetheless) from our initial model document.

In my model (Craft! Craft!) document quality relies on the writer's competence in the craft of technical writing. Okay, everyone has to begin somewhere. That's why there are junior writers and senior writers and editors. Writers get better at the craft as they learn and assimilate more techniques, as they interact with more experienced and therefore more skilled writers, and so forth, the same as one learns any craft. It isn't just something that descends from the sky into the brain of a newborn and stays there unchanged for 65 years. So it is important to have some way of determining how good someone is when interviewing--but that's a tangent I don't want to pursue right now.

What does the craft artisan bring to bear that your process cannot? Experience, judgment, intuition (which is nothing more than judgment honed by experience). This is not reducible to a fixed list of axioms and a couple rules of inference--let alone a stepwise process. (I'm talking about the details of writing here, not the higher-level process of getting a document out the door, where you and I have some agreement.)

So, to answer your question, I would know that a document is effective and that my audience's needs are fulfilled by testing the document with an audience, same as you. But before I get to that stage, I am going to apply the techniques I have learned from those who went before me and from my mentors in techwr-l and those I have devised on my own and tested in the past to produce something that in my judgment represents good craft. And I maintain that I will be more successful in the long run with that method than you will with yours.

The finishing of a document after it is written, in any system, includes reducing the number of errors to the best of our abilities. If you and I both rely on the same QA department to do that step, we can both expect the same percent reduction in errors. Suppose they catch 90% of the errors. If your document, written without care or ownership or responsibility, goes into QA with 100 errors, and if my document, written with care and ownership and responsibility, goes into QA with 50 errors, yours is going to leave QA with 10 errors and mine will have 5. As I said before, I'd rather start with uncontaminated beef than rely on irradiation after the fact.

Dick

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l