The Art of Technical Communication

In our last post we saw that technical writers need to make sense out of material that often is beyond their understanding and for which they do not have the requisite academic background to fully understand. On the other hand, experienced writers also know that they have a real job to do - and that their job entails more than just making a few cosmetic changes. They know that technical communication must ultimately serve the reader - there must be something that the writer can do to clarify the information and make reading part of the process that makes the product usable.

What then, can we do? Good writers will begin by following Alice’s strategy:

“Somehow it seems to fill my head with ideas- only I don’t exactly know what they are! However, somebody killed something: that’s clear, at any rate-”

Here Alice is using the logician’s trick of stripping away the surface semantics and looking at the basic syntax - “somebody killed something” - that’s at least some kind of beginning. And this is what experienced technical writers actually learn to do - begin sorting out who does what, what causes what, what relationships do the parts have to each other - even if the full nature of that relationship is not yet understood.

OK, so fine - the writer understands what is going on - but what about the reader? Even before technical communicators understand the subject matter, they must first try make the material “sound logical” - just by the way the words and sentences are strung together.

And so, we can take our Naming Conventions piece from the last Post and rewrite like this:

What Have We Done?

What did we do to improve this piece? Briefly, we’ve applied as many stylistic improvements as possible:

• Rewrote passive into active voice

• Turned negative expressions such as “non-unique” etc. into “positive” expressions.

• Organized the material using expressive titles - this is one of the easiest, and at the same time, one of the most effective things to do.

• Indicated where we need more information.

• Indicated where we need examples and illustrations.

• Rewrote the material to unfold in a logical, progressive manner so that the reader can follow the ideas and can see their significance.

We haven’t been able to finish the piece because we still need to gather more information. But we’ve been able to apply an impressive number of well known techniques from any experienced technical writer’s arsenal and we’ve come a lot closer to finishing the job - now we just need to gather a few more facts and everything falls into place.

Finally, Don’t Be Afraid to Interview and Get the Facts

Although Alice has heard the Jabberwocky poem first and formulated some kind of basic, overall understanding, she doesn’t leave it at that. Like a good technical writer, she eventually tracks down someone who can explain the technical terms and help her fill in the blanks - this may cause her to revise her original understanding of the piece - it will certainly help her to explain the piece to her anxious readers:

“You seem very clever at explaining words, Sir,” said Alice. “Would you kindly tell me the meaning of the poem called ‘Jabberwocky’?”

“Let’s hear it,” said Humpty Dumpty. “I can explain all the poems that ever were invented- and a good many that haven’t been invented just yet.”

This sounded very hopeful, so Alice repeated the first verse:- -

“‘Twas brillig, and the slithy toves

Did gyre and gimble in the wabe:

All mimsy were the borogoves,

And the mome raths outgrabe.” -

“That’s enough to begin with,” Humpty Dumpty interrupted: “there are plenty of hard words there. ‘Brillig’ means four o’clock in the afternoon- the time when you begin broiling things for dinner.”

“That’ll do very well,” said Alice: “and ’slithy’?”

“Well, ’slithy’ means ‘lithe and slimy.’ ‘Lithe’ is the same as ‘active.’ You see it’s like a portmanteau- there are two meanings packed up into one word.”

“I see it now,” Alice remarked thoughtfully: “and what are ‘toves’?”

“Well, ‘toves’ are something like badgers- they’re something like lizards- and they’re something like corkscrews.”

“They must be very curious-looking creatures.”

“They are that,” said Humpty Dumpty: “also they make their nests under sun-dials- also they live on cheese.”

“And what’s to ‘gyre’ and to ‘gimble’?”

“To ‘gyre’ is to go round and round like a gyroscope. To ‘gimble’ is to make holes like a gimlet.”

“And ‘the wabe’ is the grass-plot round a sundial, I suppose” said Alice, surprised at her own ingenuity.

“Of course it is. It’s called ‘wabe’ you know, because it goes a long way before it, and a long way behind it-”

“And a long way beyond it on each side,” Alice added.

“Exactly so. Well then, ‘mimsy’ is ‘flimsy and miserable’ (there’s another portmanteau for you). And a ‘borogove is a thin shabby-looking bird with its feathers sticking out all round- something like a live mop.”

“And then ‘mome raths’?” said Alice. “I’m afraid I’m giving you a great deal of trouble.”

“Well, a ‘rath’ is a sort of green pig: but ‘mome’ I’m not certain about. I think it’s short for ‘from home’- meaning that they’d lost their way, you know.”

“And what does ‘outgrabe’ mean?”

“Well, ‘outgribing’ is something between bellowing and whistling, with a kind of sneeze in the middle: however, you’ll hear it done, maybe- down in the wood yonder- and, when you’ve once heard it, you’ll be quite content. Who’s been repeating all that hard stuff to you?”

“I read it in a book” said Alice.

As technical writers, let’s hope we have the opportunity to have as sympathetic an SME (Subject Matter Expert) as Humpty Dumpty - he may be a little vain, but at least he’ll answer the questions, and he even admits when he doesn’t know. Can we hope for anything better?

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.

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.

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.

This blog is devoted to what we at YEDA call “the art of technical communication“. By that we refer to the fact that Technical Communication is that unique activity that provides a bridge between two very human worlds: the world of technology, the world that is continually created through man’s capacity to produce tools and methods to achieve certain ends; and the humanistic world of understanding, of comprehension, of knowledge - the world that can only truly be experienced on an individual level on the part of each particular human being.

Both of these worlds - the brute technological and the “human” world of understanding - truly define Man and his uniqueness. The art of technical communication is none other than the art of being able to bridge these worlds through explanation and instruction. To successfully fulfill its task, it requires many skills - ability to express oneself in writing, graphic ability, psychology, and information handling, to name the most obvious. But more than that, like any art, it requires devotion and enthusiasm. Only these last two can motivate the “artist” to continually search for new ways to coax the maximum meaning out of the technology itself - for the technical communicator, in a sense, bestows meaning on the work of technology by explaining it.

In blogging about this “art”, we’ll be looking at a wide variety of technologies, methods, issues, and even philosophies - the primary criterion for inclusion will be, in the final analysis, how much it inspires us to continue to develop our capacity for bridging those worlds of technology and understanding.