On explaining and explanations; a weblog by Pete Harbeson.

 

K-Logging

This is something John Robb has been talking about, and Write the Web interviewed him about it. A K-log is a knowledge-management weblog, where you use weblogging tools (like Blogger, Manila, or Radio) to write about your work, what happens, and what you know about. Presumably everybody else does too -- or some reasonable portion of "everybody else". Then you might use RSS to aggregate all this content, and you have the core of a knowledge management system.

It turns out that I've been building a system to do this for the past year or so. It's not yet very distributed throughout my client's company (yet), but we've reached about 1.7 million hits on a site that's available only behind a corporate firewall. It's a big company, but not that big. We've also found that other groups in the same company are doing similar things; this is clearly something an organization needs when it reaches a certain level of complexity.

I've learned a few lessons along the way, with (I'm sure) many more to come. They are:

• Posting the information is a small problem. Organizing and retrieving it is a big problem. We're working on a shared ontology and RDF metadata.
  
• Most people don't like to write. We've had a difficult time designing interfaces that encourage adding information instead of just reading.
  
• There's no substitute for good, accessible writing. We have several people who write consistently for the system. The logs show that postings from one writer get far more attention and prompt far more linking than those from the other writers.
  

Beyond the technology itself, it's becoming clear that there's a need for some organizational development in implementing these systems, to get people to contribute. And there's a need to guide or teach people to contribute -- write -- in ways that the rest of us want to read.

By the way, in the only blatant plug I've ever put on this site (and look for more if this works!), I can help solve those problems. Let me know if you want to talk about it.
posted by Peter Harbeson at 8:14 PM

 

Blogging Process

Maybe I blog in reverse. I find that I tend to start writing about something, then go find links to expand on what I'm talking about. These links are often places I've visited before and remember -- or at least recognize -- but I usually don't think of writing something when I'm looking at a site. I don't really know how other people do it, but many blogs seem to build an individual news item (or posting) around one specific link. This makes me think that maybe they're reading the site and then think of writing something about it.

This probably has little to do with anything, but I do find that the new Google Toolbar fits my style perfectly.
posted by Peter Harbeson at 12:06 PM

 

Hayek

I've recently gotten very interested in Friedrich Hayek. The first catalyst in this was this excellent essay by John Marks, which deals with a distinction I had been thinking about, but thinking in terms of "evolution" versus "design". Hayek's terms constructive rationalism and evolutionary rationalism are much more precisely what I meant. And come to find out, one of the pages on the Hayek Center site lays out the modern confusion about the political terms "liberal" and "conservative" -- another pet peeve of mine. I don't really agree with either "liberalism" or "conservatism" in the way the terms are currently used, but do think of myself as a "classical" liberal. Which is to say, not a Tory!

So on to more Hayek; I'm sure my thinking will leak out around here, as usual.
posted by Peter Harbeson at 11:59 AM

 

Irresistable Innovations

Holy smokes, this is amazing. I just installed the Google Toolbar in my browser, and in minutes it seems like it's always been there and I couldn't get along without it. This isn't an unusual effect with good software -- for instance, I feel the same way about email, terminal windows in OS X, and word processing software. But it's never before happened (to me) anything like this quickly. I wonder if this is what it's like when you try a Segway scooter! (er...I mean "human transporter", of course!)

A further thought -- people look sort of silly when they ride a Segway.
posted by Peter Harbeson at 11:32 AM

 

Visuality

All kindsa stuff about visual communication! This is an extensive annotated list of (mostly) books about visual communication, visual thinking, and the like. I'm particularly interested in the references to comics; I've been thinking that comics are where the real innovation in communication might be. Take a look at sites like this one, by Scott McCloud, to see what I mean. A good "quick reference card" or illustrated setup guide shares a lot with comics, and perhaps these kinds of documentation would be better if they adopted even more aspects of comics. Thanks to xblog for the link.
posted by Peter Harbeson at 11:29 AM

 

Communicating and Thinking

One of the things I do when writing technical material is to review what I've written to see how easy it is to think about. Writing is a sort of string through a "thought maze"; you're guiding your reader to think about specific things in particular ways. This is closely related to the "persuasive" aspects of technical communication I talked about in connection with Aristotle. There are always many paths through a thought maze, and it's important to choose carefully. Sometimes readers will come to an intersection and believe that the left turn is the way to go. This might have to do with their implicit cultural knowledge, what they learned in school, or what they know from experience in working or just living. Now, it may be your job as a writer to take them along that expected path -- often a technical writer will want to do that, as it's easier for the reader. But sometimes you need to make them turn right instead. Maybe the point you're making is that in this case they need to break with their prior knowledge and experience. And sometimes you find that it's better to back up and take a different path through the thought maze. Perhaps you can arrive at that particular intersection from a different direction, so that the turn your readers need to make does, suddenly, seem like the correct and expected path.

For instance, a piece of software might present a table of values with 9 rows. It's a WIMP (windows, icons, mouse, pointer) application, so you can simply click a row to select it. You can also, however, press the 4 key to select row 4, the 5 key to select row 5, and so forth.

You know enough about your audience that you know they will expect to be able to click a row to select it; the "keypress" method is unusual. In other words, the audience expects to be led in a particular direction through this intersection in the thought maze. You can certainly do that -- but if there's an important difference in the keypress method (perhaps it also copies values to the clipboard or something), you'll need to lead them in a different direction. You can help them expect this by "backing up" and taking a slightly different route. You might go back a few steps and emphasize that there is a new or unusual action coming up.

It's a bit difficult to pull examples like this out of thin air -- but it's far more important to be able to recognize these situations. For me, the best way to do that is to reread my own drafts, and think about thinking while I do.
posted by Peter Harbeson at 12:08 PM

 
Have you seen Rivertrout? It's a site that presents letters (and essays in the form of letters). It's a great little site. I just wish they updated it more often.
posted by Peter Harbeson at 10:14 PM

 

Persuasive technical communication

I'm rereading Aristotle's Rhetoric. It's one of those things I read in a "guided" way as part of a class -- reading in and for a class must be a lot different from the way I read on my own, because when I go back and look again at things I read in a class, I don't recognize or remember them very well. I don't know if it works the other way 'round -- I'm sure I've also had classes about things I had previously read, but I don't remember any particular reaction about it.

Aristotle doesn't talk specifically about software documentation, but he does talk about informing people through language. And about persuading an audience. I started thinking about the persuasive component of technical communication. A great deal of it is implicit. I assume that the clearest, best way to understand how to use a program is to proceed in a rational, logical manner. I assume you, the reader, have goals, and that you'll pursue those goals in a step-by-step way. This is what Pirsig called "classical" understanding. The world can be expressed as a set of boxes with relationships defined among them. This product is of the class "software", the type "office applications", and the instance "word processor". The software contains functions. Functions are accessed by commands. Well, you see how it goes.

Good technical writers often modify the classical presentation to better fit the audience. They may even modify their own personal understanding, putting themselves as much as possible in the same context as the audience. For instance, the purely classical approach focuses specifically on the system under consideration -- that is, you think and talk about the software application itself; that's the focus. The organization of your documentation, then, is derived from the conceptual organization of the software. But instead of presenting this directly, I try to widen my view of "the system" so that it includes the user and some aspects of the context in which things get done, such as the goals and skills of the user. Instead of saying "the saving of files for later access can be accomplished by selecting the Save command from the File menu", I say "You can save your file and open it again later. To save your file, select File > Save. A dialog box opens..." It's easier to read, because it's closer to the reader's actual experience. Only a few people really experience the world in a classical sense of concepts, hierarchy, classification, and so on. I generally do experience the world that way, which helps me on one end of the process -- understanding a piece of software -- but hurts me at the other end -- expressing this understanding so readers can best understand it and learn from it.

By approaching technical communication in this way, it seems to me that I'm also delivering a persuasive message about the approach itself: this is the way to understand, this is the way to think and understand.

I think this works, and while it may incorporate some attempt to persuade readers implicitly, I think that's fine. Besides, I wouldn't know how to begin to explain how to use software in, say, and emotional way.

But there are other persuasive messages in most documentation, and I'm not as comfortable with some of those. More about this next time.
posted by Peter Harbeson at 3:14 PM

 

Boycotting the Rapacious Invasive Asinine Association

It's now 56 days since I last bought a CD. And I do mean last. Like Norlin, I've never gotten into online music. I'm not very political, but this is ridiculous. So let's roll.

Uncertainty Communicated Certainly

Jim Holt says in Slate that " No scientific idea from the last century is more fetishized, abused, and misunderstood -- by the vulgar and the learned alike -- than Heisenberg's uncertainty principle." (The link is mine, not from the original.) I don't know whether I really understand it, but I do have an understanding of it, as I do Godel's incompleteness theorem, which Holt also touches on.

I learned about the incompleteness theorem in Douglas Hofstadter's amazing book Godel, Escher, Bach: An Eternal Golden Braid. That book presents some pretty complex ideas in a way that slowly unfolds them like reverse origami, with plenty of asides and digressions along that way that sort of "tilt" your point of view so you can see different facets of things. It takes a while to read -- several months for me, as I digested the material along the way. Jonathan Delacour says insightful things about this kind of presentation.

Putting links in quotes

In the previous note I inserted a link in a quote. The original quote had no such link. Is that a reasonable thing to do? Or does inserting (or removing, for that matter) a link change the quote in the same way changing the words would? Hmmm.
posted by Peter Harbeson at 9:39 AM