Three Little Words

We just bought a brand new printer from HP. I figure we buy about one printer every two months or so, on account of my husband’s business which involves printing out hundreds of photos each month. So we know from printers.

As it happened, we were enjoying a weekend at our house in Truckee, where we go to be near, but not actually at, the ski areas. My husband suddenly decided that he needed to print something out, and he tried to connect his fairly new laptop to one of the four (count ‘em) fairly old printers we had up there. As it turned out, even the newest of our old printers did not possess a USB port. So it was off to Reno, and Best Buy.

Our first impulse was to seek out the least expensive device that would print, photocopy, and fax (not that we ever fax anything). But we were drawn, as if by printer gravity, to the latest HP model, which was advertised as “wireless network ready.”

The salesperson, who was an HP employee, was very knowledgeable. This came as something of a shock, since we frequently shop at Fry’s. Anyway, she explained all the features of the printer; especially the ink cartridges that for reasons unknown cost much less than other ink cartridges, and the tray for photo paper that is able to coexist with the regular paper tray.

Then I asked about the “wireless network ready” claim. Just how ready is this printer, I wanted to know. Do I have to connect it to a computer to configure it, or will it find the network on its own? You see, we didn’t want to buy a USB cable if we didn’t absolutely have to, because though we were ready to spend $300.00 on a printer, we wished to avoid spending $20.00 on a cable when we knew we had a couple dozen spare USB cables back in Palo Alto.

The salesperson did not pretend to know the answer to this question — another culture shock for us. She led us to a second salesperson who, she said, could explain the wireless setup.

This salesperson explained the setup using special rapid high-tech salestalk that sounds like “Yada yada yada configure yada yada yada automatic yada yada yada no problem.” And then he uttered those three little words:

It Should Work.

Hey! I wanted to yell. Come on now! I am a trained technical writer. I have more than 20 years of experience writing end-user documentation. I know the uses of the phrase, “It Should Work.”

I held my tongue, though, figuring I’d probably already embarrassed my husband enough by interrogating not one but two salespeople. We gambled (this was Reno, after all) and took the printer home, cable-less.

It Did Work.

The simple setup instructions that came with the printer let us through typing in the encryption key for our home network, and both our computers — one Mac and one Windows — found the printer immediately.

Good work, HP! Be sure to give credit to the instructional designers who came up with those setup instructions. And remember, tell your salespeople not to use those three little words.

How Dumb Can You Get?

Star Trek fans: remember those Next Generation episodes in which Data would do something out of character, and Picard would suspect Data was malfunctioning? Picard would say, “Data, perform a self-diagnosis,” and Data would search through his circuits (he was an android, oh you non-Trekkies), find the problem, and tell Geordi exactly where to perform the repair or download the patch.*

So why doesn’t my Mac tell me where to find the System Preferences?

I’m in the process of doing a rapid review of Mac Help, since I will be working on some aspect of it. My first stop was the Spotlight Help, for the simple reason that though I realized that my Mac contained something called Spotlight, and that Spotlight had something to do with finding things, I had never actually used it.

I opened the topic “Setting Preferences for Spotlight,” and read:

1. Open System Preferences and click Spotlight.

Eh? Open System Preferences? And where might I find System Preferences?

Okay, I know where to find System Preferences. But what if I was a naive user? What if I was Bart’s Mom? The instructional designer who wrote this help should have included, as part of step 1, exactly how to perform the step. So like a typically annoying new employee, I asked about this at a meeting. It turns out that it is deliberate, because the writers at Apple are faced with the same problem as Help writers everywhere: the Mac OS, unlike Commander Data, is unable to explain itself.

Normally, the writer solves a problem like this either by writing more text (“Open the Apple menu and choose System Preferences”), or by including a picture of the interface element that must be clicked. But we want less text, not more! And we don’t want to bulk up Mac Help’s footprint by including a bunch of pictures.

And most of all, we think it’s just plain silly. Why should we have to embed a picture of the System Preferences icon into the Help steps, when the darned thing is just sitting down at the bottom of the screen in the Dock, where the user can plainly see it if he or she only knew where to look?

Why isn’t the Mac smart enough to say, “You want Preferences? Wait a sec; I’ll circle the icon for you.” Or, even better, “Allow me. I’ll open it for you.”

Amusingly enough, the Mac used to do this back in the day, when Mac Help was based on Apple Guide. But the Apple Guide technology wasn’t pushed forward and is no longer used.

I think the reason why we never seem to make any headway in online help is because the Powers That Be continue to see it as a replacement for “The Book.” Even in open source projects like Flock — actually, especially Flock — the people making the decisions see online help as something external to the product. It’s like the little paper manual that comes with the refrigerator or washing machine.

But online help is not a book! Online help is the machine explaining itself. It should be like Data on Star Trek. But when the machine can’t show you where it keeps its icons, or menus, or whatever you’re trying to find — well, then it just looks like a dumb refrigerator.

——–

* Okay, sticklers, in “The Schizoid Man” Data is unable to detect the problem, due to sabotage.

Rewind

I’m at Apple.

For the past few days I’ve felt like I’m in a time warp. I’ve rewound my life, and returned to Apple. I’ve resumed my old position as an instructional designer, in my old department, with several of my old friends. I’m back in the old building on Infinite Loop, just down the hall from the office where I used to sit. I’ve even got my old employee number and email address!

Did the past eight years really happen? Did I leave Apple for Netscape, and work on Navigator and Mozilla and Flock? I must have, because my brain seems to be filled with information about browsers that can only come from over-exposure.

The beauty of it is, several of my fellow Netscapees are here, two. They came to Apple, of course, to create Safari, and now I get to work with them once again.

For a while now I’ve had it on my mind to write a little something about why it turned out to be so hard to work at Flock, much as I loved the place. And why I find it so hard — impossible, maybe — to work on open source projects in general.

I’ve come to a two-pronged conclusion about it: open source communities are tough on women, and open source communities are tough on non-engineers. Since I’m a female non-engineer, I’m doubly cursed.

Soon I will share the stories that support this two-pronged conclusion. But for now I must continue rewinding my professional life back to Apple.

It’s good to be back.

Deprived of Words, We Labor On

The estimable Lloyd has asked me to put into writing my philosophy of instructional design for on-screen reading, which can be summed up in seven words:

"We have their attention for five words."

(Note the irony)

People don't read anymore. I'm not sure how anyone becomes educated these days, because from what I've observed in usability testing, people are not going to read to the end of this sentence, much less finish Moby Dick.

But still we wish to communicate with these word-deprived people. Technical writing research scientists are hard at work these days, searching for new ways to reach people whose eyes automatically slide away from the content-loaded text on the screen and over to the little blinky thing on the left.

One concept is to communicate mostly in screen captures. So instead of writing "Open the File menu and choose New Blog Post," the author presents a little picture of the File menu, open, with the pointer resting on the New Blog Post option. Maybe you'll even throw in a little picture of the bog editor window, with an arrow implying that an open editor window is the consequence of choosing New Blog Post. This approach is promising, and I'm trying to adopt it in my own work. (Perhaps one day you'll tune into this blog and find a post composed entirely of screen pictures!)

My own personal concept, my favorite alternative, is to re-write all user's guides as graphic novels. If I could draw, or work with an illustrator, that's the approach I'd use. I'd love to write an explanation of the client-server relationship entirely in cartoons!

Meanwhile, we must do our best. The open source community is especially taxed, because it has sensed the need to communicate more effectively with "end users," but doesn't know how, and doesn't employ a lot of technical writers.

So here are six tips for writing clear documents. If you follow these tips, your sentences will be shorter with no sacrifice of meaning. These tips take less than one minute to read.

Number 1: Use direct verbs

USE: "Now that the basic files are ready, we can create the topbar."
NOT: "Now that the basic files are ready, the topbar can be created."

Number 2: Speak directly to the reader, as if you're having a dialog

USE: "If you don't have experience with XUL, you may want to read the tutorial."
NOT: "If the reader doesn't have experience with XUL, he or she may want to read the tutorial."

Number 3: Use present tense

USE: "In the chrome.manifest file, we define the important directories."
NOT: "In the chrome.manifest file, we will define the important directories."

Number 4: Keep text as short as possible

USE: "Click OK."
NOT: "Click the OK button at the bottom of the dialog box."

Number 5: Avoid quotation marks

USE: "Open the Flock menu"
NOT: "Open the 'Flock' menu"

Number 6: Don't use all caps; avoid capitalizing tools, widgets, etc.

USE: "Creating a Flock topbar"
NOT: "Creating a Flock Topbar" or "Creating a Flock TOPBAR"

It may seem that there is no relationship between the subject of this blog post and the topic about which I claim to be writing: namely, exposing and trashing the Dominator Model.

But if you look hard enough, you'll find that everything is related to the Dominator Model. For the abbreviated attention spans that seem to keep people from reading more than five words at a time, I blame the patriarchy.

Gotta Run Now!

C'était bref, mais court.

Sad to say, I have decided to depart from Flock and from open source endeavors in general. I'm going to ride off into the sunset. Not on a horse — No, I want one of those light green vespas.

During this period of relative quiet between milestones, it has become clear to me that Flock doesn't need a principal writer. I've done a lot of writing at Flock, and helped Eli conduct usability studies; I've even written the staff biographies. But I'm not doing much design, and design is what I love to do, and what I do best.

Although nearly all software companies insist on referring to what I do as "technical writing," I'm really an instructional designer. I analyze the users, figure out what they need to learn about a piece of software, discover how they like to learn, break down their objectives into sets of simple tasks, and, finally, make it easy for them to find the smallest bit of knowledge that will let them continue on their way, doing whatever it was they were doing before they were rudely interrupted by a lack of information.

Much as I like working at Flock, where I get to be among smart, interesting people all day, and where I've learned more in the past six months than I did in the previous four years, I'm not doing enough design to keep me challenged and engaged. And I have concluded that open source projects, in general, are not structured to take advantage of my particular skills.

I know, I know, open source equals open community and everyone gets to contribute. But Flock is my third open source project, and I find myself back in the role I didn't like at Mozilla, and that I was just starting to dislike at Eazel when it folded. I have become a "wordsmith." Not that there's anything wrong with that! Actually, I like the sound of the term "wordsmith," and I am flattered when people refer to me that way. (I'm not so sure I'm worthy of the term — Geoffrey is more of a wordsmith than I am, in the sense that he forges new words — good ones, too!)

Here's my role as a wordsmith: during the intense three or four weeks before a major milestone, people bring me word-deprived objects: dialog boxes, menu items, error messages, etc. They ask me to come up with coherent text. I can do that, no problem. But I'd rather be in on product design from the beginning, at the point where features are designed and named.

It seems to me that a wordsmith provides a service: you bring me a dialog box that needs to be re-worded, or a wiki that needs to be re-organized, or a release notes document that has committed apostrophe abuse, and I fix it up.

A designer, on the other hand, works with a team to create something new.

While I don't mind providing a wordsmithing service, what I really like to do is design.

You may remember one of Apple Computer's early television ads for the Macintosh. The ad showed a big, daunting stack of books — representing all the manuals a customer would get with an IBM PC. Suddenly, an elegant, slim, white volume dropped from the sky and landed softly on the table — the Macintosh manual.

Apple understood, early on, that the manual was part of the product. This understanding was reflected in the position of the Apple publications group within the larger company. As an instructional designer at Apple, a writer is involved early in a product's cycle. The writer is there for planning and execution, and of course, for the party at the end.

I'm not saying that Apple is a mecca for writers. But at Apple, the book that goes in the box, and the UI text and help system that go in the machine, have to look good. Apple's words are on the front line of communication with customers, and Apple knows that. Apple's manuals and help systems win awards as a result.

And I'm not saying that good design can't come from open source projects. I think that remains to be seen. Flock has a shot at it. Flock is currently looking for a good User Experience person to hire. (If you know of any, send them to flock.com.) If open source projects in general, and Flock in particular, can figure out the magical re-structuring that allows non-engineers to be part of the core team, then they may become the mecca for designers.

I'll be watching and cheering from the wings.

Good luck, Flockers! And thanks.

P.S. I'm not giving up blogging. I will continue to write in this space. Maybe Geoffrey can come up with a new name for "Vera's Flock Blog."

Wiki: For and Against

There’s a discussion going around Flock these days about where information about using and abusing Flock should go — In the wiki, where anyone with a login can alter the information, or in a carefully crafted piece of instructional design?

I am an instructional designer, and I have to confess that I have a certain prejudice in favor of carefully crafted writing. If I had lived during the Middle Ages, I would have been a member of a writers’ guild. (Until they burned me at the stake for being a woman who could read and write.)

As you might guess, I have a lot to say on this subject. And for the most part I’ve kept it to myself, thinking it was best for me to try to learn the mores and customs of open source before bestowing my wisdom upon the community.

But since Eli recently questioned the practice of putting carefully crafted writing into Flock’s wiki, and Lloyd responded with a firm, pro-wiki position, I thought I’d try to present both sides of the debate in my blog, and maybe gather some enlightening comments. So here are my cases for and against the wiki. 

The case against the wiki

Put yourself in the place of a regular, day-to-day user of the Internet. My aunt, for instance. She’s just set up an account at her bank’s online service, she’s logging in, and her browser wants to know if she’d like that password to be saved.

She hesitates, then clicks Cancel. "Hmmm.." she thinks, "I don’t know. What does this mean? Is it safe?" So she decides to get more information before proceeding. She opens the browser’s Help menu and chooses "Support," which looks more promising than "Release Notes" and "Late Breaking News."

Suddenly, the online banking screen is swept away. An unfamiliar page appears in its place. She sees the page’s title — "Wiki." But where is her bank’s log in page?

She tries to find a topic that explains password-saving. Her eyes scan the right-hand column. "Community Portal… Recent Changes…" What the heck is this? She misses the search box (where the word "search" is artfully lowercase and subtle in color). But she spies the topic "Internet Security" and clicks it. The page that appears is all about encryption. There’s nothing helpful here, but she tries clicking a link. "Encryption methods can be divided into symmetric key algorithms (Private-key cryptography) and asymmetric key algorithms (Public-key cryptography)…" Hastily, she clicks the Back button. Here’s the wiki again. These paragraphs about encryption appear to have been written by more than one person… there’s a cogent paragraph that might have something to say about online banking, but it’s followed by one that seems to have been written in language only a mathematician would understand.

She gives up. Online banking is supposed to save her time, but how convenient is it when she can’t even get an answer to a simple question? Besides, she’s got to get to work. She’s the physician on staff in the hospital’s pediatric intensive care unit, and her patients are waiting.

The case for the wiki

Now put yourself in the place of a college student who has just downloaded a new browser, and wants to know if it will work with his favorite extension.

Naturally, the first thing he does is to just try it — why not? What’s the worst thing that can happen? But once installed the extension doesn’t quite work the way it should. He wonders if anyone else has tried this, and pokes around the browser’s website looking for information. Finding only a Support link, he clicks it. WTF…. ! A little window opens offering "Help Topics" and a prominent search box. He types in "extensions" and hits Enter with more force than is really necessary. Nothing. Just some lame information about how you can download "helper files" to extend your browser’s capabilities.

Damn, this thing looks like it was written for somebody’s aunt.

 

Got Some Explaining To Do

“I’m a doctor, Jim, not a cable modem technician!”
“I’m a doctor, Jim, not a..”"I’m a doctor, Jim, not a bricklayer!”
“I’m a doctor, Jim, not a command shell!”

I just searched on “I’m a doctor, Jim” and got around 700 hits. Lately I’ve been emphatically repeating something similar: “I’m a technical writer, not a ___” Much of the writing I’ve been attempting to do fills in that blank. I’m not sure what you call it. It’s the writing for the Flock web site, revision two, and I’m pretty sure I’m the wrong person to be doing it. Oh, I can explain things. I can explain how the Star and Tag dialog works till the cows come home. (Fortunately, it doesn’t take that long.) But I can’t come up with a snappy little phrase to capture the essence of Star and Tag. No, I couldn’t do that if my very life depended on it. The best I’d come up with is some sort of feeble phrase that screams “DORK!!!”

So what is a technical writer? In this age, a technical writer is someone who consumes information about about complex subjects, and produces an explanation, written in terms that can be understood by pretty much anyone with a moderate degree of education.

I’m also an instructional designer. An instructional designer analyses material a reader needs to learn, and figures out the best, most logical way to present that information. An instructional designer asks questions like, “What are the characteristics of my readers? What tasks do they want to do? What do they need to know in order to do these tasks? What vocabularly do they understand?” And so forth.

So I am an explainer. The kind of writing I do has more in common with teaching than with writing catch phrases. In fact, writing catch phrases can be the opposite of technical writing, because eye-catching exclamations — You’ve come a long way, baby! — often obfuscate. They do not explain.

I’m not saying that it’s impossible for me to coin a phrase. I do that, sometimes. Maybe about once or month or so.

Yesterday, when I said something like the above rant to a colleague, he responded, “Don’t thrash yourself!” He doesn’t understand. I’m not thrashing myself. I don’t feel bad that I can’t write “that way.” If anything, by my way of thinking, I’m complimenting myself.

If I had to choose one bit of technical writing as the piece that makes me most proud, it would be an online document I wrote while at Netscape, on the subject of Internet privacy and security. It explained in simple terms many of the issues concerning people at the time: what is a cookie, how does encryption work, how does one choose a good password, is it safe to use a credit card online, etc. In the process of writing it I had to read about and understand encryption. And as I’ve told my daughters many times, you know you understand a subject when you can explain it to someone else.

I see my role at Flock as threefold. First and foremost, I want to help make sure that our software explains itself. Self-explantory software is my holy grail. Second, I want be the managing editor of a database of information, some of which I author, that is a resource for people who have questions about Flock or want to learn more. And finally, I want to be Flock’s information architect, and try to create appropriate structure for the flood of information we will inevitably produce (because all high tech communities do).

And now, because I like to be perverse, I will close this post with a catchy tag line that captures the essence of what it is that I do.

“I’m a technical writer. I’ve got some explaining to do.”