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

YEDA Presentation

admin Uncategorized

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

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.

admin Uncategorized, philosophy