The Art of Technical Communication

No, this isn’t a post about fictional technical writers - or even about technical writers who write fiction.  This is about what technical writers can learn and apply from literature - from novels, stories, and drama.

Technical writers are in the business of providing information for a certain clientele - but providing information is not exactly the right description - technical writers don’t provide telephone books or directories - we provide information in the form of something a lot more organized, and a lot more meaningful.

Learning theorists and Instructional Designers have consistently noted that information presented as a “story” with a recognizable theme, a dramatic progression from one point to the next, and a meaningful context will have a much greater chance of being understood , remembered, and applied.  I am not referring to the well known mnemonic properties of a story structure  - the ability of stories to increase retention is something that is well known. The more important aspect of stories, and the less well known,  is the way they act to convey meaningful information - to take diverse facts and turn them into something coherent where each fact has its place of significance in the overall scheme of things.

It is just here - in knitting together a mass of facts to form a unified and meaningful whole -  that many technical writers fall short, and instead are content to simply “provide the information”. Instead of interpreting the facts in such a way as to amplify their significance, writers tend to concentrate on language and presentation techniques: clear, short sentences,  good looking fonts with appealing graphics and neat page layout - all of which are important, of course, but none of which truly deal with the larger picture of making information meaningful to the reader.

Of course, meaning can be conveyed only when the writer is convinced that there IS some meaning in the information - in point of fact, this standpoint is essential for any meaningful communication to take place. What all this means is that for writers to be truly effective, they must first convince themselves of the meaningfulness of the information that they are transmitting - and afterwords they must find a way of translating this meaningfulness to the reader.

admin Editing, Uncategorized, Written Communication Fiction, Meaning, Signficance, Technical Writing

As Technical Communicators, we find ourselves judging our work on a day to day basis. Its clarity, accuracy, and “friendliness” are typical concerns for the conscientious  technical communicator. Beyond that, we judge the usability of our writing - just how easy is it to use, and how valuable?

We talk about “Technical Literature, and the question arises as to whether it should actually be regarded as a real form of “literature” - and whether  it should be subject to literary criticism, in much the same way as a  play or a novel. This may seem bizarre, but stop and consider, for a moment, the utility of such an approach.

We may, for example, find that some writers have a direct, simple, “Hemingway” style of writing - while others write in  longer, more involved, sentences and paragraphs that reminds us of Proust. The typical response is that the “Hemingway” style is the “correct” one for technical literature. But is it always? Doesn’t it depend on the subject matter, the intended use of the book, as well as the skill of the writer? A well constructed Proustian User’s manual intended for advanced users, may satisfy much more than a short, laconic Hemingway approach. This is not to say that unnecessary words, or long, clumsy sentences, are good - but not every long sentence is clumsy, and not every 40 word sentence  is filled with unnecessary words. A passage can be dense with words and long sentences, and yet convey meaning in a way that engages the reader, and provides a more satisfying experience than a stripped down, laconic guide.

Writing, above all, must “engage” the reader. To engage readers is not the same thing as simply conveying information. To engage readers is to give them something meaningful, which is to say, to give them something that has value within the context of their lives. When we speak of meaningfulness with regard to technical literature, we refer to the value that something has for the professional concerns of the reader. Just plunking down information is often not enough - it is the minimum measure of meaningfulness, but certainly not the full measure.

admin Uncategorized

admin Uncategorized

More and more I am confronted with the fact that many jobs today - in law, government, medicine, finance, commerce - require the same skills that we teach in Technical Communication - clear instructions, conveying information to someone in a brief, yet comprehensible, way, and managing to make information relevant to a particular audience. With that in mind, what is the point of calling it “Technical” communications? What is “technical” about it?

Today, it is not only hi-tech products that require clear instructions and explanations - this type of writing is essential in many areas because those areas have themselves become more complex. The “glue” that holds complex systems together is communication. The efficiency of any modern, bureaucratic system is contained in its flow of communication - and if the communication that flows is not understandable, the system breaks down.

So what should be rename Technical Communications?

admin Uncategorized

I believe that any really creative activity should engage you so deeply that you do not notice the passage of time - you become so absorbed in creating the instruction, the web copy, or the story, that the “real” world fades into the background, along with sense of time. Conversely, it’s when you realize that you’ve forgotten the time, that you know that you’ve been working creatively - had you been aware of time, it’s safe to bet that your heart wasn’t really in your work to begin with.

admin Uncategorized creativity

Word’s Automatic Numbering is often problematic - numbering new sequences can be a problem, and often the numbers don’t come out right. Using field codes avoids these problems - field codes are very stable, and once you learn to automate their use, they become indispensable for creating dependable numbered sequences. The following clip shows you how to do this:

using_fieldl_codes_to_number_instructions

admin Desktop Publishing

YEDA Presentation

admin Uncategorized

Examples of mistakes in technical documentation are not hard to find - and I don’t think anyone, no matter how experienced, can ever be fully rid of them. I’m not talking about grammar or style, things that some writers get so carried away with, and which you can find readily enough in just about any technical manual. Nor am I referring to actual technical errors - it is always a dispute as to who is really responsible, the writer, or the SME. The mistakes that I have in mind are errors of information sequencing, in clearly communicating what is meant, or what you want the user to do. These mistakes are solely those of the technical writer - and to eliminate them requires sensitivity, training, and patience.

Consider the following step for Upgrading Wordpress:

Step 1: Replace WordPress files

..

2. Delete your old wp-includes and wp-admin directories.

3. Copy the new WordPress files to your server, overwriting old files in the root, except perhaps the wp-content folder (see “NOTE“below). You may use FTP or shell commands to do so. Note that this means *all* the files, including all the files in the root directory as well. If you use the default or classic theme and have customized it, then you can skip that theme.

NOTE The wp-content folder requires special handling, as do the plugins and themes folders. You should copy over the contents of these folders, not the entire folder. In some cases, copying the entire folder may overwrite all your customizations and added content.

Also take care to preserve the content of the wp-config.php file in the root directory. This file contains current settings for your existing installation, e.g. database sign-in information. Occasionally new versions of WordPress add statements to this file. (E.g. in version 2.5 the SECRET_KEY variable was added, see Extended upgrade instructions). Compare your existing file with the new installation file which is named wp-config-sample.php. Either transfer your settings to the sample-file and rename it to wp-config.php or copy the new statements from the sample file into your current file.

The underlined parts are what are problematic - and the line in red font makes it even worse. First, I’m to overwrite all files in the root directory (”except maybe the Content directory) - a few lines later I am told to make sure to overwrite ALL files in the root directory. Fine. BUT… , later, after I’ve done just that, there is this little addition “Also, take care to preserve the content of the wp-config.php file in the root directory”. Gee, thanks for telling me that AFTER you’ve told me to overwrite everything else! Lest you think I’m just nitpicking here - I discovered this documentation error after I myself fell victim to it and had to frantically locate the old wp-config file that I had luckily backed up on my computer long before.

Presenting information in a logical sequence is the backbone of giving technical instructions - in fact, of giving any instructions. Once you realize that users are not just going to read your instructions, but actually follow them, you need to pay close attention to the logic of your writing. The less familiar readers are with the material, the more slavishly will they follow the instructions - line by line, and to the letter. You cannot play games with users like these - unsure of themselves, they perform each line of the procedure, step by step - when they finally get to a step that cautions them to NOT do something that you instructed them to do a few lines back,  they will never forgive you - nor should they!

admin Errors

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?

admin Editing

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