Seeing my work through others' eyes

A few days ago, I got to the office and popped in for a look at BlobCo's intranet - meaning it was a pretty typical morning. At least it was until I spotted a post by our trainer.

The trainer's post was a compare-and-contrast piece explaining the difference between training and documentation. Having been unaware that there was any confusion on this point, I was interested enough to read it. Sometimes I find out that my assumptions (such as "everyone knows the difference between training and documentation") are completely mistaken, and I was willing to believe that I had reached one of those moments.

Except that wasn't what was going on.

The post mentioned training briefly, then focused on what documentation is: It's reference material, it's purely descriptive, it's not something you read all at once.

I fully agree with that last one. But the first two aren't an accurate depiction of the work that I've focused on at BlobCo: Task-based help. It's not about describing the menu items and buttons. It's about getting people from being stuck to getting our product to do what they want it to. It's also about jogging people's memories when they've forgotten what they learned in the training sessions.

I took away a handful of insights from this:

• Lots of people still don't know what I really do.
• Lots of people think they know what's in the documentation before they even look, so they don't bother to look.
• Even if you're positive that you know a thing, it's always worth researching it before you write about it...because you might still be wrong.
• It's really easy to irritate people by mischaracterizing their work.
• Getting irritated means you're paying attention to the wrong things.
  
• Having your work mischaracterized is a gift: it's your signal that you need to get better at your 30-second explanation of what you do and how it contributes to your organization's overall goals.
  

OK, that feels better. I got some constructive ideas out of this, and I came out of it with my sunny side up.

To blog or not to blog

A colleague remarked on Twitter that he's thought about blogging, but didn't feel that he had anything of value to say. I started thinking about why I follow him on Twitter: Because he's the sort of person I'd want to hang out with if we lived near each other - insightful, funny, and obviously passionate about his work. His tweets are always worth reading. I can learn from him, be inspired by him, and enjoy his wit.

And this man doesn't think he has anything to offer on a blog, so he hasn't been blogging.

One of the other threads that day was to do with the Dunning-Kruger Effect, which for years I'd been calling "meta-cluelessness" - the idea that some people lack the information or skill to discern that they lack information or skill.

My colleague seemed to be exhibiting the flip side of this effect: Highly capable people tend to underestimate their own skills and knowledge quite consistently, assuming that everyone knows at least as much as they do. If you've been doing a thing for a long time, and have quietly become an expert at it, you may take for granted what you know about it. You may assume that, since you've managed to learn how to knit socks, or rebuild engines, or write help that keeps customers from making tech support calls unless something actually breaks, surely everybody else in the entire world must know how by now.

But you're wrong. Lots of people don't know what you know. If you talk or write about it, some of those people will pay attention. Some of them will find your style engaging, and will want to learn from you. You'll enjoy getting to know some of them through their comments. You'll learn from some of them.

What are you waiting for? Your fans are looking for you. Start writing!

Recipes, assumed knowledge, and indexes as teaching tools

Consider: Recipes and cookbooks are one of the oldest forms of technical writing. They tell you how to complete specific tasks, and what results to expect. Cookbooks also have explanatory material to help you understand the techniques and terminology in the recipes, along with conceptual information - why you knead bread but handle pie crust dough as little as possible, which ingredients can be substituted for others.

When my Grandma Mulholland passed away years ago, I inherited her recipe box - and realized that we technical communicators can learn a lot from trying to follow old recipes. Grandma's fudge recipe (transcribed here exactly as my grade-school educated Grandma wrote it) provides some examples.

Quick Fudge
2 1/4 C Sugar
1/2 Cube butter
1 small can Carnation milk = 2/3 cup
Boil 5 minute stir constantly
Remove from heat, add 1 1/2 C Mineture Marsh mellow and 1 Pkg of Choc Chipps - 1 t flavoring
Beat untill all disolved. Add 1 C Nut Meats & stir them in
drop by spoonfull on Wax Paper...buttered dish - cut when cool

Grandma made a lot of assumptions about what people know and what they can buy at the grocery store. Fortunately I could remember what was available in the average grocery store in a smallish city in Indiana back when the world was a large place and other parts of it were far, far away, so I was able to figure out what this all meant.

The 2 1/4 C sugar was pretty straightforward; it meant granulated white cane sugar, the default choice of sweetener in the midwestern USA during the middle of the 20th century. If Grandma had meant brown cane sugar, she would have said so - and she never encountered any other kinds of sugar.

Half a cube of butter? A bit tougher. Looking at the quantities of the other ingredients, I decided that was half a stick: 2 ounces, or 4 tablespoons.

Carnation milk would be evaporated milk. Two kinds of milk came in cans when my Grandma started using this recipe: Carnation milk, which was evaporated; and Eagle Brand milk, which was condensed and sweetened. I remain grateful that Grandma saw fit to note that a small can is 2/3 cup.

Miniature marshmallows are still with us, so that was no problem.

I had to think hard about the chocolate chips. These days I buy them in 24-oz bags, but they weren't available in such large packages when Grandma was still making fudge. I racked my brain. Grandma was not one for buying large quantities of stuff and then keeping it around. Ah - so it would be the smallest size, otherwise she would have said what size bag. So it's six ounces of chocolate chips. I used six one-ounce squares of Baker's chocolate instead, and the fudge came out right.

That brings us to "1 t flavoring" - a teaspoon of...what? Well, vanilla, again because that was the default in mid-20th century cooking in the midwestern USA. You put it in most sweets, and it was nearly mandatory in anything with chocolate.

And that cup of nutmeats - that had to be chopped walnuts. If you climbed in a time machine and went to a Kroger's or A&P in Indiana circa 1965, right beside the six-ounce bags of chocolate chips, you'd find bags of chopped walnuts. There would probably be slivered almonds as well, but they were for exotic stuff like green bean casserole. You'd never have put them in fudge. And the pecans were out of the question. Only a Southerner would put them in fudge.

So here I sit, nibbling on fudge that tastes exactly like the stuff that Grandma made every Christmas, and reflecting on how much I had to know to make that recipe turn out right.

It's making me think about what a hard time I've had learning some popular software tools, such as Adobe Illustrator and Microsoft Excel - in each case, there was a body of assumed knowledge that I did not have. In each case I had trouble using the help because I did not know the names of things. And in each case the help index failed in its teaching function - I could not look up familiar terms and get "See" or "See also" entries that pointed me to the help I needed. Sometimes I muddled through until I stumbled upon something that worked, sometimes I asked a friend, sometimes I gave up.
Well, fudge.