The Art of Technical Communication

One of my favorite authors is Lewis Carroll - although I’ve been fascinated by his work since childhood, it was studying the Philosophy of Language at the University of Pittsburgh that really laid the foundation for my affection for the author of Alice in Wonderland, Through the Looking Glass, and less well known books such has his The Game of Logic. Carroll was actually a Mathematics professor and a logician and his work is loaded with allusions to the way in which we take language for granted. Naturally, examples from his whimsical stories found their way into my professor’s illustrations, coming as they did from the British philosophical tradition.

What does all this have to do with Technical Communications? Quite a lot, actually. Technical editors are constantly required to edit and revise pieces that they don’t fully understand - or even have much information about. That’s part of the game. For example, suppose you received this gem to turn into something readable:

Here we have something that sounds, well…- like something right out of the Through the Looking-Glass. Compare with this poem that Alice discovers in a book:

`Twas brillig, and the slithy toves
Did gyre and gimble in the wabe:
All mimsy were the borogoves,
And the mome raths outgrabe.

“Beware the Jabberwock, my son!
The jaws that bite, the claws that catch!
Beware the Jubjub bird, and shun
The frumious Bandersnatch!”

He took his vorpal sword in hand:
Long time the manxome foe he sought –
So rested he by the Tumtum tree,
And stood awhile in thought.

And, as in uffish thought he stood,
The Jabberwock, with eyes of flame,
Came whiffling through the tulgey wood,
And burbled as it came!

One, two! One, two! And through and through
The vorpal blade went snicker-snack!
He left it dead, and with its head
He went galumphing back.

“And, has thou slain the Jabberwock?
Come to my arms, my beamish boy!
O frabjous day! Callooh! Callay!’
He chortled in his joy.

`Twas brillig, and the slithy toves
Did gyre and gimble in the wabe;
All mimsy were the borogoves,
And the mome raths outgrabe.

Poor Alice! - when she first reads the poem she is alone and has no help from anyone - she reads it assisted with nothing but her own native interpretation of the poem. Beyond that, Alice’s reaction to the poem is what most experienced technical writers eventually learn to say:

“It seems very pretty,” she said when she had finished it, “but it’s RATHER hard to understand!” (You see she didn’t like to confess, even to herself, that she couldn’t make it out at all.)

How typical - none of us likes to admit that we don’t understand half the stuff we’re required to write about - but that’s part of the game. However, even more important than that minor cover-up, is the fact that experienced writers realize that in order to get the job done, they have to develop a healthy sense of “tolerance of ambiguity“. if they want to complete the assignment before the product is actually released, they must look the other way when it comes to trying to fully understand everything they are writing about - there are some things that will always be beyond the writer’s grasp. Next time, we’ll look at what we CAN do with pieces like this, other than pretend to understand them.

admin Editing

An interesting study by Ian J. Quitadamo and Martha J. Kurtz, demonstrates that learning to write is an effective method for learning to think critically (2007, Learning to Improve: Using Writing to Increase Critical Thinking Performance in General Education Biology) .

Thinking skills acquired include analysis (ability to break down information into separate components for greater understanding), inference (the ability to draw conclusions from available evidence), and evaluation (the ability to make reasoned judgments). The writing skills were acquired through having students write short essays on thought questions related to lab experiments in biology.

i have never conducted a formal study of the benefits of learning how to write about technology, but anecdotal material from following a large number of graduates over some 15 years of teaching technical communications indicates that technical writing can be used to acquire a wide range of thinking skills. Let’s look at some of them:

Ability to Read Closely and Interpret Texts

One of the first things that technical writing teaches is the ability to read and interpret primary technical material. Students learn that material submitted to them for editing or rewriting is filled with ambiguities, contradictions, and inconsistencies - students soon learn to identify these and to take the initiative to solve them. Skills acquired include learning to read closely, learning to question material, and learning to draw inferences the material.

Ability to Organize information Logically

Another skill that technical writers learn early is the ability organize diverse material into some kind of logical scheme. This usually entails learning how to construct a hierarchy of titles, then acquiring the skill to identify which material belongs under the relevant title.

Ability to Critically Review One’s Work

The ability to critically review one’s work is not the first thing that students learn to do - it is usually learned as the result of repeated criticism from the instructor. Eventually, students learn to read through their work and revise it before sending it out - they learn to apply the accepted standards of technical writing including direct, simple language, user friendly style, and appropriately brief, relevant paragraphs.

Ability to Evaluate Audience Expectations

Becoming a writer really involves learning to think of your audience before you write, while you’re writing, and when your reviewing. Keeping the audience in mind is really the central skill in the art of writing - no less for technical writing, than any other kind of writing. But the structured nature of technical writing - operating procedures, various types of explanations and overview material, makes it easy to teach the skill of writing for an audience - the instructor can quickly point out where the student’s writing has failed to take into account what the reader knows or expects to know - and this process is much less ambiguous and than say writing a novel or a poem.

Ability to Evaluate Relevance

The ability to evaluate the relevance of information is actually part of understanding audience expectations. Writers learn to evaluate information for its relevance for performing an operation, understanding a process, deepening the reader’s appreciation of a feature and its uses, etc.

Ability to Summarize

The ability to summarize technical information is a central skill for technical writers and students should learn to do this fairly well in any thorough technical communication training. This expresses itself mainly in the ability to sift through a collection of facts and “raw” technical material, and to be able to boil it down to a brief, informative, and relevant summary.

Why “Technical” Writing?

Although any writing, when taught correctly, will improve a student’s ability to think critically, comparatively speaking, technical writing is a “fast track” to acquiring these skills. What makes technical writing different? For one thing, the student’s writing is much easier to check and errors are often black and white - it is easier to show the student what is lacking. Missing lines in an instruction, sloppy recording of machine responses, leaving out critical information in an explanation before an instruction - all can be quickly pointed out and there cannot be much disagreement - the instructor can very quickly show the student why the writing is flawed by simply having the writer, or another student, “try out” the explanations and instructions to see if they supply the required information, and in a format that can be easily read and understood. This is much easier than to trying to point out flaws in an essay on politics, history, or literature where the student may find it difficult to understand what is lacking in the writing.

Another thing that makes technical writing an ideal form of learning to write and think critically, is that assignments can be given on very specific topics and a simulated set of primitive source materials can be provided to the student, along with the actual system, normally software, to be documented. This method enables the instructor to more accurately evaluate student performance and point out flaws and problems in the student’s writing.

admin Thinking Critical Thinkiing, Teaching Technical Writing

Anyone who has been in technical communications for any appreciable time, should reread Pirsig’s revolutionary Zen and the Art of Motorcycle Maintenance. And, if you’ve never read this counter-cultural hit from the 70’s, all the more should you read it now.

Unlike any other book, Pirsig’s epic draws connections between philosophy, the art of writing, the meaningfulness of technology, and our deepest values and understanding of the world. And it does so in a brilliantly told story which is both a personal and a philosophical odyssey, a journey into the meaning of life and how we understand reality.

But it is Pirsig’s concept of “Quality” that speaks most to people whose daily life is spent trying to come up with the best way of presenting information. For Pirsig, Quality is something that underlies all of our cognitive judgments, a kind of mysterious “ground” upon which rests the entire world of perceived objects, people, and events. Despite the mystery of defining exactly what “Quality” is, Pirsig’s underlying argument is actually quite simple -

The Argument

Here is Pirsig’s argument in a nutshell:

1. The “world” out there is actually built up out of our cognitive judgments, i.e. out of the way that we perceive and classify things.

2. There are always competing ways of perceiving, classifying, and understanding the world - thus we are constantly making decisions as to what constitutes reality.

3. The basis for distinguishing between competing ways of understanding something (i.e. between various theories or explanations) is simply that one way seems intuitively “better” than the other.

4. The mysterious thing that determines why we prefer one theory over another is what he calls “Quality” - and it underlies all our judgments, both moral and cognitive.

5. Therefore, the theories that we adopt that condition the way we see the world, i.e. that determine what we take to be “real”, are actually products of Quality and of our drive to find it.

Quality and Technical Writing

What does this have to do with Technical Writing? Well, actually, everything! Pirsig taught English Composition - and the ability to distinguish between good and bad writing is an example of how Quality eventually prevails. The Technical Writer is normally in a position that requires communicating technical information to a wide audience of developers, implementers, or end users. On the surface of things, writers must satisfy two masters - on the one hand, they need to satisfy the Subject Matter Experts (SMEs) who ply them with technical information and whose main concern is that the documents are accurate and technically correct. On the other hand, there are the intended readers who need to both find information quickly and comprehend it. The writer needs to satisfy the demands of the SMEs, usually under time constraints, while making sure that they meet the needs of the readers for whom the document is written in the first place.

Writers whose main concern is making the SME happy run the risk of alienating the reader - while those who mainly worry about giving the reader a great experience in terms of clarity and good looking, easy to read documentation, but who don’t bother to check all the nitty gritty details, run the risk of passing along defective documentation that may someday backfire.

There is a way to beat this conflict, however - the solution is for technical writers to adopt the principle of “Quality” as their overriding value. These writers are going to produce documentation that really does the job - because they are going to find themselves critically reviewing their own work, comparing it with standard work that serves as ideal models for both style and organization, and they are going to keep working on the document until they “feel” that it represents the best document that they can produce given the time they have to produce it. Instead of passively bouncing back and forth between conflicting interests, writers will actively pursue the ideal of Quality and, with that in mind, see that their documentation meets their own standards of what constitutes good technical communication.

admin Uncategorized