The 24 by 5 Tech Comm Blog

1. People like to ask questions even if they already know the answers.
2. A week ago is ancient history.
3. You’re way more likely to ask a competent friend for help than to go to an expert stranger.
4. Making mistakes in a low-risk environment is fun.
5. There is no such thing as a final answer.
6. We learn a lot more from conversations than we do from lectures.
7. A compliment never hurts.
8. Anonymity doesn’t get you anywhere.
9. Your level of excitement about a project as very little influence on how much others want to help.
10. If you ask, there’s always somebody who can help.

I ran across a great explanation of RSS on i’d rather be writing — it’s originally from Common Craft here. It’s been doing the rounds of tech writing blogs and I think it might even have made it to BoingBoing.

And I can see why. It’s a simple, brilliant explanation. RSS is one of those ideas that somehow becomes complex whenever you try to explain it. It’s actually not hard to find pretty good explanations of RSS, but Common Craft have gone one step further by making something engaging and fun.

And that’s the important point. Watching that video made me feel like I was having RSS explained to me by a smart friend. Technical writing is widely believed to be boring which is only very slightly better than being totally incomprehensible. Boring content is forgettable content, and once you forget something, you may as well never have spent the time and energy reading it in the first place.

I predict that the tone and style that Common Craft use is going to get more and more popular as experts start to coexist with enthusiastic armatures and more and more people start to write documentation out of a love for the material. In my Utopian vision of future technical writing, everything we read will be fun and we’ll learn not because we have to, but because we enjoy it.

Last night, partly inspired by Kate and Katicus Sparrow, I tried Second Life. If you don’t already know, Second Life is an on-line roll playing game without the game. It’s a visual, interactive environment that combines instant messaging with the ability to go “places” and “do” things.
I had read a lot of hype about Second Life so I was a bit skeptical. On the whole though, I was impressed. The ability to meet people, particularly people on the other side of the world, in such an open-ended setting, is quite charming.

Second Life has an interesting approach to documentation: There is none. Maybe that’s not exactly true — I’m sure there’s a lot of documentation in Linden Labs somewhere, and they made it very clear that F1 would take me to their help files — and there were times when I was frustrated. There were times when I couldn’t figure out what to do, or what I was supposed to do, or how to do it — but I never pushed F1. It was almost a matter of pride that I didn’t press F1, and in the end I didn’t need to.

Why not? What is it about Second Life that makes a manual unnecessary? I think it’s three things:

1. They start you off right away with an optional tutorial. Tutorials are nothing new, but the Second Life one is particularly clever because it’s not necessarily linear. It’s broken up into topics, and then modules within those topics — but I can go from one module to another in a any topic just by walking over there, or, if I get too frustrated I can skip them all and just look around. The key here is that they are presenting structured learning opportunities, but still alowing the user to pick and choose. Oddly, knowing that I didn’t have to finish the tutorial actually encouraged me to get to the end.

2. You get immediate feedback. Because of how visual Second Life is, success or failure is usually quite clear. If you fall from a twelve story building, then you did something wrong when you tried to fly. It reminded me of learning to drive. By imitating the rules of the real world (selectively) Second Life made me feel like the system wasn’t arbitrary, and that made practicing fun because I could apply real-world logic and get back immediate results.

3. There’s a community. You can actually see other “people” walking around, talking and doing stuff. Actually, this was a bit stressful for me. It’s a bit embarrassing, walking off bridges, when you know that the digital avatars standing near by are representatives of real people and that they can see how little you know. But the flip side to that is that most of the folks I met were pretty happy to explain things. What that means is that Second Life has created a situation where the community does a lot the training of new members. And of course, watching other people do things shows new members some of what they can look forward to.

As for me, I think I’m going to make a habit of dropping in to Second Life occasionally. I’m not terribly fond of the idea of spending even more time sitting in front of my computer, but I can’t shake the feeling that Second Life and Linden Labs are the tip of something that’s going to grow and evolve in weird and interesting ways — and I want to see that happen.

PS — I just ran across Sony’s Home for the Playstation 3. We’re just seeing the beginning of this. Just wait until we have direct brain interfaces…

I read a great post on The Creative Tech Writer this morning, answering the question, once and for all: Is technical writing boring? I won’t steal Jenny Berger’s thunder — read her answer for yourself. Her exasperation just about oozes off the screen.

As for myself, occasionally I’ve found tech writing a bit boring. I hate to admit it, but yeah, there are times when I have to use a little willpower to get through a project.

But expecting any job to be totally and completely devoid of boredom is like expecting a marriage to be 100% free of disagreements. If that’s your standard for success… good luck.

The truth is, the things I like about being a technical writer greatly outweigh the things that bother me about it. Among those positive qualities, the best is that I actually get paid to learn about things! All I have to do is break down whatever I’m learning about so other people can learn about it too. I was doing that throughout my whole university education and I was the one paying for the privilege.

Besides, boring is a state of mind. Next time your faced with a stubborn paragraph, ask yourself, what would Dr. Seuss do?

In an ideal world, I would spend my afternoons eating lunch with important people at big technology companies. They would pay the bill, laugh at my clever jokes and hire 24 by 5 Tech Comm on the spot. Oddly, things haven’t worked out exactly like that.

Instead, I’ve met a lot of owners of small and medium sized businesses that have little or nothing to do with technology. This has been challenging because, unlike people at tech companies, they often have no idea what technical writing is, let alone how it could conceivably be useful for them.

I’ve always had the gut feeling that good technical writing could help any kind of business, not just technology related ones — but at first it was really hard to articulate why. It wasn’t until I saw how incredibly busy most business owners are, and how inefficiently a lot of them use their time, that I realized what technical writing really is and how it could help them.

The mistake most people make is identifying technical writing based on it’s topic (technology) instead of its method. Technical writing is a style of writing that breaks down complicated, specialist knowledge into easily understandable chunks, and arranges them to maximize their usefulness readers. That kind of documentation is crucial to growing businesses because it takes the inspiration and ideas of the entrepreneurs and distills them into systems that other people can reliably follow.

Technical writing gives businesses a framework to base their growth on. Without that kind of structure growth is just as likely to result in an inefficient mutation as a viable business model. In a lot of ways, technical writers complement business coaches, in that they’re both trying to help owners design and implement reliable systems.

I probably don’t need to write this, but if you’re a business owner and you haven’t read the E Myth, turn off your computer, go to the library or bookstore, get it and read it.

Then give me a call.

There is a really interesting New York Times article that has been floating around, generating a lot of discussion. It’s about Joshua Bell, a world class violinist who apparently spent a morning busking in Washington DC with a Stradivarius, and was spectacularly ignored — in spite of the fact that he was an acknowledged master, playing some of the most beautiful music in the world, on one of the finest instruments in the world.

The general response to this experiment seems to be horror that most of us are so desensitized by the brutal routine of daily life that we would completely miss out on something so beautiful. I pretty much agree with this point of view, but find it odd that it takes a “famous” classical musician to make people sit up and notice how much of our lives we miss by being slaves to our obligations and habits. We’re surrounded by beauty all the time and most people never even realize it.

So if most people can’t see spectacular beauty when it’s right in front of them, what are the chances that anybody will read what you wrote? Most people already think that technical writing is about the most boring thing there is, right?

That’s the bad news. The good news is that technical writers have two powerful advantages:

1. People already have a mental model for technical writing — they know what to expect. Technical writing is about teaching people how to do things. It’s not about telling a story or entertaining. There’s nothing wrong with a touch of character or humor, but writers need to respect the expectations of readers. Try to be clear, don’t try to be clever. If you sneak “literature” into documentation it will either be ignored like Joshua Bell, or it will be seen as a waste of time and annoy people. Understand your reader’s state of mind, and write to it.
2. Nobody snuggles up with a hot cup of cocoa on a cold winter night to enjoy a new software manual. People go to technical writing because they have problems they need to solve. The manual is a means to an end, not an end itself — and that’s a good thing! It means that, unlike Joshua Bell, you already have a contract with the reader. Writers fail when they don’t realize that they’ve made a promise to their readers and instead feel like their responsibility is to describe the product they’re writing about. Your reader has agreed to spend their time on your document, and you’ve agreed to help them solve their problem. As long as you can do this, you don’t need to be an artist.

Being an artist is a great thing, but genius in the wrong place isn’t genius at all. As technical writers, our job is to help people achieve their goals. Pour your heart into that novel, but remember that while you’re writing a user manual, you’re a concierge, not a violinist.