On explaining and explanations

 
This is the best reading list I've seen in a long time. I've read about 2/3 of it. Cool, I love having a generous helping of things to read.

[later]
Hmmm. I wonder why this book is on the list?
posted by Peter Harbeson at 9:38 PM

 

Writing, Teaching, and Teaching Writing

Another of the Saturday sessions today, in the technical writing program I teach. The Saturday sessions are generally "labs" of some sort; more hands-on and informal than the regular Tuesday night lecture-style class. I'm new to teaching; I've been doing this only since last September. But even in that short time I see enormous differences in the two venues, and I can only attribute this to the differences in context and environment. The students, after all, are the same. I'm the same. The subject matter, in a broad sense, is also the same. I'm thinking about just what it is about the context that makes such a difference.

One of the questions I'll bring up in the next lecture -- or maybe the next lab -- is whether all this technical writing theory and practice can be communicated through technical writing itself. In other words, what you do as a technical writer is communicate complex information as a set of instructions that your audience can follow on their own. There's no teacher present, no mentor, no expert -- just the book (or help system). This works for some things -- I can write instructions for using a piece of software, and be pretty confident that most people will be able to learn to use the program without taking a class. But I'm less sure that something more open-ended and complex, like technical writing, can be as completely communicated when written. A teacher is much more than a book, in other words, even when lecturing from detailed notes.

I say "theory and practice" but it's mostly practice. There is some theory underlying technical writing -- at least to me -- but it's old stuff, dating back to the Greeks, and I haven't always been successful in pointing out the connections. Perhaps it's a general lack of knowledge about Greek philosophy -- or maybe I've just got it wrong. I found the first points of connection when I read Zen and the Art of Motorcycle Maintenance, which I reread every few years. It's still one of my favorite books.
posted by Peter Harbeson at 9:35 PM

 

What really captures attention?

Doc Searls has an idea about a "million customer march" on Washington to put our collective foot down about things like the asinine licensing terms proposed for Internet radio. Maybe what we need is a virtual march -- what if a million websites addressed this issue all at once? Tyromaniac suggests a banner -- I'm thinking more like everyone making their entire home page address the issue.

Music industry "business" types appear to be no-talent shakedown crew and organized criminals that do things like charge artists "breakage fees" for media that never break, successfully extort money from you when you buy a blank cassette or CD, and have been getting away with Enron-style accounting and worse for fifty years. Maybe that should be "entertainment industry" where I say "music industry".

They never should have been allowed that first shakedown. Why do we flat-out fight other forms of organized crime, but put up with this crap from these guys?

posted by Peter Harbeson at 11:22 AM

 

How to Howto (part2)

The most important part of technical writing is the state of mind of the technical writer. It's an amalgam. Beginner's mind, in the Zen sense, enables you to see the way something works with fresh eyes, noticing everything, unfiltered by all you may have learned -- and keeps you open to everything new. A scientific approach enables you to proceed carefully and systematically through an interface or system, making useful notes and detailing both what you understand and what you don't. Empathy enables you to take the user's place and see how "features" fit together to accomplish real tasks. Seeing the whole system reminds you to understand and consider the context in which your instructions will be used -- the whole system includes the user, not just the machine or program. The writing mind helps you communicate with your audience.

All of these are more than mental states; they are practices. It is not enough to "feel empathy" for your audience; you must put it into practice by testing, trying, getting reviews, contacting users.

While this is, for me at least, a clear and simple explanation of how to communicate complex information, it's far more descriptive than prescriptive. It's easy for me to say "just think this way and you'll be able to do it" -- it's considerably harder to truly explain how to think in a particular way. And it's even more difficult to actually do it. There are probably tens of thousands of pages in print trying to explain how to master each of these practices and disciplines, and people spend years mastering a single mind state.

So it's hubris for me to put it this way...maybe. It's not that hard though. You don't practice any of these in isolation. You practice being a technical writer, and thus practice them all. I learned all this along the way. Now I teach it in classes. And perhaps I'll be able to explain it all here. At least, what the hell, I'm giving it a shot.
posted by Peter Harbeson at 4:33 PM

 
Yesterday I talked about my mission as a technical writer. Here's an example of what I mean, by way of Rebecca's Pocket. This story describes the British TV show Back to the Floor. The premise is simple: find a CEO willing to spend a week actually doing the tasks that his company markets, film him, and create a story around the results.

Robert Thirkill, creator of Back to the Floor, says: Bosses are always surprised at how much knowledge exists further down the ladder.

In other words, these "bosses" do not understand their subject matter, and they're not in touch with their audience. I'll go out on a limb about this: a CEO who is a good technical writer would not make these elementary mistakes.

posted by Peter Harbeson at 12:57 PM

 

How to How-to

I'm a technical writer, and I'm on a mission to spread some technical writing memes. Y'see, technical writing is a more powerful and broadly applicable collection of practices than you might think. The principles of technical writing have recently emerged, in incomplete and somewhat garbled form, in a variety of fields from Knowledge Management to eLearning to the Semantic Web. While all of these fields get some of it, or sort of get all of it, they've also gotten it wrong enough to be significantly "off". It's like they aim at the moon, and are off by a measly half-degree. Doesn't seem like much from where you start, but you end up utterly screwed.

Technical writing has to do with focusing on your audience, understanding your subject, and being utterly, spectacularly clear. It's an art, not a science. It's not widely understood. But it generalizes amazingly well. I'm putting together some examples and demonstrations, and I'll post 'em individually as I complete them. In the meantime -- instruct somebody!
posted by Peter Harbeson at 9:35 PM

 
"Too much formality in design is a waste of time", says Joel. This resonates with my own experience, both in creating software (which I haven't done very seriously in quite a while) and in creating information that helps people use software.

Years ago I wrote a program that supported a training exercise in which you practiced being a manager, making decisions over a simulated several-year period. It was one of the bigger and more complex programs I had written to that point, and I was, I thought, about 75% finished. I realized I had to add some function I can't precisely recall, and discovered that I had to go through practically all of my own code just to figure out how to make the new function work. The whole program, y'see, was one big monolithic function.

For some reason, I made exactly the right decision. Instead of struggling to figure out how to add the function, I put that on hold and designed the program as a set of small functions. I say "designed" instead of "redesigned" because I hadn't really done any design work at all the first time through; I just started coding.

I can't tell you how many times I've used what I learned writing that program. Not the coding -- the design.
posted by Peter Harbeson at 11:09 AM

 

Serious, schmerious

Who the hell is that guy in my skin? I wondered. I had just observed the guy in my skin posting a truly pompous, idiotic, dweebily mature discussion comment on a popular (the popular>) blog. "Unhelpful?" "Very disappointed"?!! What horsehocky -- I don't write like that! But (gag) apparently I do. Or did. Shit.

David Brooks, writing in The Atlantic, perhaps saw some of this monstrous tendency growing in himself. Or found some other guy in his skin. In Inspired Immaturity -- The midlife crisis as a patriotic duty he says " Ours is the most vibrant nation on earth because it is the most childish, and therefore the most creative and daring." He says a bunch of other ironic, interesting, smart and smartass things too, ending up with " Today conformity is once again a bigger threat than chaos. The forces of seriousness and maturity are everywhere closing in. If this trend continues, we will soon be living in a country unworthy of the greatness that was P. T. Barnum..."

So that's it. Enough of this middleaged, conservative (which I ain't even -- except apparently I am), corporatized crap. Looking for me? I'll be the guy on the chrome Harley.

posted by Peter Harbeson at 9:27 PM

 
I've settled the writing tool problem for the time being. When I'm updating my main site I write in either BBEdit or vi and upload using ftp. And that's exactly what I'm doing here on the blog, with one additional component: I paste what I write into Blogger and publish from there. Cool. Or cool enough, at least. And yes, I know I could ftp right from inside BBEdit, but I'm so comfortable with the command line tool I'm just using that for now.

posted by Peter Harbeson at 6:17 PM

 
There's an article at eLearning Post about "Empathic Instructional Design". Maish Nichani starts out with some research findings that most online instruction (which he calls "elearning courses") is "boring" and "text-heavy". Nichani introduces the idea of "empathic design", a design technique based on user observation.

The article contrasts the empathic approach with both "Instructional System Design" (ISD) and "Analyze-Design-Develop-Implement-Evaluate" (ADDIE), both of which are "detached" approaches that are neither user-centric nor task-centric.

It seems to me that nobody researching this area knows about techical writing, which takes user-centered design, task-based approaches, and task orientation as fundamental principles. And eLearning Post claims to represent "Corporate Learning, Community Building, Instructional Design, Knowledge Management, Personalization, and more."

This is an axe I'm going to be grinding a lot in the near future: a number of fields have entire communities of gurus and pundits opining about "information", "knowledge", and "learning", yet these entire fields appear to know less collectively about how to communicate clearly and simply than a single competent technical writer. They're much better at inventing new jargon to make things seem Complicated, of course. Technical writers are not good at jargon because we know its purpose is never to communicate. (Quite the opposite; the purpose of jargon is to redirect attention.)

Organizations, large and small, could do worse than to simply institute the principles of technical writing whenever they face a problem having to do with information.
posted by Peter Harbeson at 11:31 PM