Coffee and Documentation

by Lynn Miller on April 17, 2009

For me, travel requires coffee.

So I was happy to see a coffee maker in my hotel room while I was at CHI – particularly since CHI starts at 8:15am. Being an upscale hotel, my room had an upscale coffee maker laid out nicely on a tray.

 

There was an instruction card propped up in the coffee maker. My guess is that the instruction card was created after the 500th call to the front desk to say that the coffee packs were twice the size of the basket they are supposed to go into and the cheerful front desk staff were getting less cheerful when telling the guests they should stuff it. (The coffee pack into the basket, that is.)

 

This got me thinking about the design of documentation.  Can you spot the missing step in the (unfortunately slightly fuzzy) instructions below?

Do you think that, even in the early morning, there are people who end up slurping coffee off the table top because the instructions didn’t say to put a cup in to catch the coffee? I rather doubt it.

I like the concept of not treating the readers of documentation like idiots. This little card gave me the information that I needed and couldn’t know ahead of time (how much water to use, the filter looks too big but is the right size, only push the button once) without wasting my time by giving me information that I either already knew or could easily guess (I can get water from the sink, I need to use a cup).

Can we use this concept in software documentation? What parts can safely be left out so that we are only highlighting the pieces that are really needed?  This is different than trying to reduce word count by using simple writing concepts (which I am a big fan of).

Back in the 1980’s, software documentation had to include instructions on how to use a mouse. This was dropped when mouse usage became part of the general knowledge people were expected to have -- just like catching the coffee with a cup is.  Are there concepts in our documentation that are just as obsolete, but we’re keeping them to be complete? How do we root these out?

Something to ponder.

Comments

[Lira]

Terry found noodles in her coffee maker in NYC - yuck! This got us all thinking that people sometimes use objects and tools beyond their intended use...

[Lynn]

I've found there to be a dearth of manuals in hotel rooms. Maybe people are taking them as souvenirs. :-)

[Jeen]

I suppose "RTFM" written in big letters and stuck on the wall might save a lot of phone calls for help.

[David Baldacchino]

Great post!

Firms go through the same issues when trying to document procedures. It's difficult to hit the right "soft spot". You have users that just need a little nudge (just give them the highlights & key points) and others need every little step outlined to them. I guess it's the difference between conceptual learners and those that rely heavily on memory.

If you overcook it, you end up annoying most users. I guess this is why we have coffee cups with writing on them warning us that "Contents are hot!" (well, it's really because of lawyers), or why we have to live through yet another presentation by flight attendants on how to fasten a seat belt.

With interactive documentation, one could show users the essence and give them control to reveal more detail between each procedure (if any obvious ones are skipped) but with printed or non-interactive documentation, it's a lot harder. I would rather see a condensed version followed by a super-detailed version which once could skip past.