just write click

I say I don’t listen to many podcasts, but I’m currently listening to Design Critique’s podcast with Gerry McGovern at the User Interface 12 conference. Timothy Keirnan was a MTSC classmate of mine and does an excellent job interviewing usability professionals for us all to learn from.

One of Gerry’s comments that really hit home to me is that Google’s entire ad revenue generation is based on 17-word ads. Seventeen words! I complain about the 140-character limit in Twitter, yet, lots of money is being made on seventeen words.

Also, they both noted that generally, web site design is so flat - rectangles and boxes are pretty much all you get. So websites should be useful and functional. And words matter. For example, if you are a non-native English speaker approaching a website for information, you’ll be more successful by recognizing the word “search” quite quickly.

I was also reminded of Harry Miller’s podcast, The IM Model of Technical Writing, about writing end-user documentation as if you were responding to a friend’s Instant Message (IM). Topic-oriented writing such as DITA encourages you to encompass ideas in discrete bundles - topics contain only as much information as is needed. From the specification: “A topic is a unit of information with a title and content, short enough to be specific to a single subject or answer a single question, but long enough to make sense on its own and be authored as a unit.” Very IM-like, I’d say.

An enjoyable couple of podcasts, and quite appropriate for my current thoughts about the value of good writing along with good design.

My writing teammates and I are working through our favorite ways to start a project and do user and task analysis. The exercise forced me to write down what it is I do when starting a new project.

My formal training began in graduate school but my practical training happened at only two different companies, Rockwell Software and BMC Software.

But the basic principles I follow are: do task analysis by reading everything available about the feature, reading about the typical users (personas are great for this goal), searching the internet for examples of the features in use, and then interviewing people to fill the gaps in the information available to me.

Next, I start by outlining what topics should be written and if there is a set of templates available I will always use those to the fullest. I guess that my outline-first approach is why the TOC standards are important to me. If I’m editing existing content I keep the users’ goals in mind while editing.

I have used the Hackos and Redish book User and Task Analysis for Interface Design and I like it. Also, I have A practical guide to usability testing by Dumas and Redish on my bookshelf.

Usability is so integral to task analysis, which is why much on the web is usability-based rather than writing-based I believe.

Basic task analysis: http://www.usabilitynet.org/tools/taskanalysis.htm

Task analysis grid using an Excel spreadsheet: http://toddwarfel.com/?p=16.

I’m using this spreadsheet only slightly modified to analyze user tasks for setting up a certification program and it has been so helpful so far.

Six Steps to Better Interviews and Simplified Task Analysis:
http://www.adaptivepath.com/publications/essays/archives/000295.php

I’m sure that this post doesn’t capture all of the things I do when approaching a writing assignment but it helps to write it down and analyze my methods to look for improvement.

In this month’s Central Texas DITA User Group meeting, we had an excellent presentation about linking using DITA maps and relationship tables by Scott Stark from IBM. He’s located in Austin and supports about 150 writers in California. His presentation is available for download from the Files section (membership required) of the ctdug Yahoo Group. When the video of the presentation is posted, I’ll be sure to link to that as well. In the Files section he also includes examples of the files he demonstrated with sibling or family links, sequential links (automating previous and next topic links), required links, target only or source only, and showed the power of linking that can be done with DITA automatically.

For even more information about the power of linking with relationship tables, Scott highly recommends Linking DITA Topics Through Relationship Tables by Kylene Bruski of Comtech Services, Inc.

What caught my attention this particular meeting is the de-emphasis on inline links, or links within the paragraph context as the text is read. This blog entry has many examples of inline links in the first two paragraphs. It’s not really topic-like. Scott stated that there are basically just three types of links in DITA - inline, citation, and related links. That is a precise summary. I believe that he most powerful portion of DITA and DITA maps are the management of related links. But I also believe that inline links have value as well, even in a topic-based system like DITA.

Inline links are what we are commonly finding as we continue to analyze our existing content. We have relied on cross-references in our FrameMaker documentation and online help to shorten tasks by having the first step link to another task, by collecting lists of cross-references to suggest what to do next, and for glossary definitions as popups within the text. We’re still trying to determine the best course of action for migrating those links.

While deliverables that contain lots of cross-references are not topic-oriented, I am starting to wonder if inline links are going to be the stage for usability battles to be waged because of sites like Wikipedia that heavily rely on inline linking for context. Since the user can probably safely assume that inline links in a help system go only to places within the information deliverable, the inline link offers valuable context to the reader and doesn’t “remove” the reader from the user assistance system. Also, placing related links at the bottom of a page where the reader has to scroll to in order to view might be another usability problem.

So, does DITA have it wrong when it comes to usability of links?

On Don Day’s suggestion, I did some searching for studies that would back up the topic-oriented link collection method that DITA advocates. According to this usability study titled Where Should You Put the Links? Comparing Embedded and Framed/Non-Framed Links, related links embedded on the left hand side of a screen layout were “searched faster (though not significantly), was perceived as being easier to navigate and to find information than the other link conditions.” I also found some excellent blog posts by SEO experts when trying to find usability studies to back the DITA preference for collecting links in one location. While SEO is more about optimizing pages for search than the actual readability of the page, there are excellent arguments back and forth for when you should use inline links and when they are actually a distraction. I first read “Inline Linking Bad for Usability” and I enjoyed his examples - one written with all inline links, and one written with all related links at the bottom. I would wonder if blogs with inline links and Wikipedia will “train” readers that inline links are helpful to click but perhaps only after they read the entire entry, our readers will be more able to perform their tasks despite inline links.

Another blog post by an SEO is on “The Value of Embedded Links” and one of his arguments is “So, regardless of where links are, chances may be that some visitors will miss links. Ideally, the way around that is to make sure that links within content can be easily seen.” I see this as a “scattershot” method, however, rather than analyzing your content and audience to determine the best placement of links, you would just place them everywhere you could, if you follow this argument to a logical conclusion. So perhaps DITA is doing the right thing by forcing their opinion of usability of user assistance systems by encouraging us to collect links in one location. My concerns after reading some usability studies on the topic are that perhaps 1) the placement of the related links could be improved and 2) as readers are trained by other information deliverables such as wikis and blogs that inline links can be clicked after reading the entire entry, DITA will be considered old school for its lack of inline links.

Perhaps we should change the DITA Open Toolkit transforms so that related links are in a on the side of the page instead of clumped together at the bottom of the page. I think that overall, DITA and topic-based writing has been a little unforgiving with the use of inline links. Since I can’t find usability studies that back up the claim that grouping related links together is better for users, and especially with sites like Wikipedia succeeding with inline links, I think that both types need to be given equal importance and flexibility for applying in the right way for the right audience and deliverable. What do you think?

From a recent post by Kathy Sierra at Creating Passionate Users, “What if instead of seducing potential users to buy, we seduced existing users to learn?” I don’t really like the title of her post, which is Why marketing should make the user manuals! because I do think that skilled and talented technical writers can be organized in different locations in the company. But I do like the heart of her question above, about convincing users to learn and care about the technical details of a product. Armed with technical knowledge, our products and accompanying manuals should help us kick butt at our jobs or hobbies.

Manuals as sales tools

She also talks about arming your sales force with these slick glossy manuals and using manuals to sell your product. I’ve discussed a “Tech writers as sales reps?” article and dissected and questioned the best practices in that article in a series of posts. Yes, well-done technical manuals can help close the deal.

Yes, there’s real skill to this tech writing if you want it to be good

I think that good tech writing is a highly-valued skill and includes all the components of design, layout, conviction/convincing, inspiring, motivating, and teaching that the ultimate manual should include. Since I’m motivated to help everyone realize the value of good manuals for selling and sustaining products, I have written commentary on the best practices for tech writing from the “Tech writers as sales reps?” article, including Best practices in tech comm for fit in the organization, Best practices in tech comm for customer feedback, and Best practices for Document Management Systems.

A great example of a “slick” manual

Many tech writers are passionate about their jobs and just need the opportunity to let that passion spill over into their writing, conveying the technical information that inspires users to evangelize about the product they’re using. One such interesting example of a slick manual showed up in the comments on Kathy’s post — a link to a user manual for a microphone. Now, the opening style of the writing has a few too many exclamation points for my taste as a writer and reader, but it is a neat example of bubbling enthusiasm for technical topics and a product that you’ll get the most out of when you thoroughly understand the technical details. Here’s the opening paragraph that is enjoyable but not necessarily technical.

We know you hate to read manuals. So do we! But because the Snowball is such a unique recording tool, we really hope you take the time to familiarize yourself with its features and try the suggested application tips that are designed to help you get the most out of the Snowball. You might just learn something too! With proper care and feeding, the Snowball will reward you with many years of recording and performance enjoyment and it won’t end up as a pool of water on your desktop! Now on with the show. (No refrigeration necessary.)
This introduction sets expectations that this is not a typical user manual while also offering very compelling reasons to continue reading. So I did.

Next, I was delighted with the explanation of the technical design of the mic. A little twinge of early elementary school target audience but not too pedantic.

The Snowball uses two separate capsules to offer you a wide variety of applications. The first capsule generally “hears” what’s right in front of it in a fixed cardioid pattern with a neutral sonic signature (engineering geeks call this unidirectional). The second capsule generally “hears” everything around it with a brighter overall sound (engineering geeks call this omnidirectional).

The best part of this manual is that it offers scenario information for each type of sound that you might be capturing with the mic. Here’s the text from the Strings section. The Snowball is an excellent choice for miking all members of the bowed string family. In general, the diaphragm should be angled toward the instrument’s bridge to pick up a blend of body resonance and bow sound. On bass and cello, placement from 3 to 6 inches in front of the bridge is usually ideal. For violin and viola, it is preferable to position the microphone 1 to 2 feet above the instrument. Angle the diaphragm toward the bridge for more bow sound and low tones, or toward the tuning pegs to capture a more diffuse, brighter sound.
Great practical advice with immediate steps to take to troubleshoot certain problems. That’s good tech writing to me.

Back to the heart of the matter… bridge the gap

I think that my main point on this topic of blurring the line between the stereotypical “boring black and white” manual and “enticing full color” marketing material is that while it may seem like there’s a dividing line between manuals and the rest of the docs that go out with a product, that chasm should be bridged early and often. Keep the conversations going between your users and writers as well as your writers and sales and marketing to continue to help users kick butt after the purchase.

Kathy says she’ll follow up with a Part II to this post and I look forward to reading more. She has a very engaging and enjoyable blog, one that helps you think about passion in new ways.

Found this iPod Pocket Dictionary on my Gizmodo feed yesterday, and thought I’d pass it along. Since it’s the pocket version of the Merriam Webster dictionary, it’s only about 40,000 words. Interestingly, it appears that the interface doesn’t make you spell out the word by scrolling through letters, instead you select the first letter, then scroll through the choices. Sounds like the right design balance (limit the lookup choices, but ensure the interface isn’t frustrating to the user.)

Now, an additional feature that would really combine the audio power of the iPod with the dictionary would be a pronunciation guide that speaks the word aloud on demand. I really appreciate that feature in the online version of Merriam Webster at www.m-w.com. I’m usually a decent speller but can really butcher word pronunciations. The example word on the product site, abstract, has different pronunciations for the verb and the noun. Seize the opportunity for the technology mashup when you can, I say.

If you didn’t already know that business and IT have real connections that matter to customers, here are a couple more examples.

I like the user experience blog This Is Broken. There are two recent entries that caught my eye as examples of connecting IT procedures to customer-facing services.

This post showcases an error in the printout on this receipt from an ATM application. Hee hee.

*This is line 1 of the store message*

*This is line 1 of the marketing message*

Another This Is Broken post is about a misprint on the label of a pair of jeans. Granted, this is probably a counterfeit label example, but, it relates to IT in front of customer facing products. The printout is a data source error ” =if(Label=”",”RMA”,”?”) ” which is funny text to read when it’s out of place on a label that’s supposed to contain say, sizing or brand information. I know, I know, you can’t blame IT for those necessarily, and the Internet conspiracy people think the image is photoshopped, but I like the image nonetheless.

Both examples are good reminders that IT and data does make a difference to the quality of the product or service that faces customers. Online shopping experiences are always good examples of how IT can make or break a sale. This Is Broken tends to get to “meatier” IT connections for consumer products, and I appreciate that approach.

Lately I’ve seen several good articles or tidbits about specifications and was surprised to see some hatred for them

You know, specs. That short little list of things that is supposed to be the technical description of a product. I just read this New York Times article of the commandments to electronics manufacturers and it’s good stuff. Several of the commandments are directly related to documentation, and to troubleshooting, but sometimes the documentation is used before the purchase, such as reading the specs on a digital camera.

As Gizmodo points out, and Commandment III also describes, sometimes megapixels aren’t the whole story.

“III. Thou shalt not hype irrelevant specs. The digital camera industry wants us to believe that a camera’s quality is somehow related to its number of megapixels. A seven-megapixel camera must be better than a four-megapixel one, right?

It’s the same with computers, where millions of people still believe that the higher a computer’s megahertz, the faster it runs. (To its credit, Intel has recently started playing down that simplified statistic.)”

For digital cameras, the sensor size, which collects the light for the image, limits the sensor’s ability to get the whole picture, so to speak. So a 10-megapixel Sharp camera with a CCD sensor of only 38 square millimeters compared to a 10-megapixel Canon 1DS Mark II with a full-frame sized sensor of 864 square millimeters, well, you just can’t compare on megapixels alone because one the sensors will collect a lot more light for you. It seems as though there’s an hype encroachment even on technical specifications where you have to educate yourself just enough to know which specs matter and which ones don’t.

My other favorite commandment from this list is:

“I. Thou shalt not entomb thy product in indestructible plastic.”

With the holiday season coming up, I don’t look forward to the battle with toy packaging. We plan to unbox (debox?) every toy before wrapping in gift wrap. With the twist ties, zip ties, and extremely sticky tape that binds toys to their display box, it’s always a struggle to free the toy from its temporary home.

Back to specifications. Both as a writer and a consumer, I solemnly swear to examine all specifications for hype, and de-hype them before documenting them for a customer or making a purchase as a customer.

Becoming a true user advocate

Of course, as soon as I post about profiles, I read a great blog post about being sure you put real users in your head. While personas are helpful, they are only helpful to a point. It’s much more important to know your users personally and know real people that will let you know when you’ve missed the mark.

From “ Creating Passionate Users: Subvert from Within“

-8<-
Speak for real users… not fake abstract “profiles”.

Represent real people, not the abstract notion of “users”. Rather than saying, “what users really want is…”, refer to your collection of specific user stories and talk about real people. When you bring up users, talk about specific people with real names and experiences. Too many companies use fake “profile” characters as a way to think about real users (e.g. “The typical user is a thirty-five year old sales manager with a four-year degree and two kids who uses a computer for…”). While that’s better than not thinking of users at all, it still puts both a physical and emotional distance between the company and real users. After all, it’s impossible to truly care about pissing off the “fake” 35-year old sales manager (even if you give the profile character a name, like “John”), but almost everyone starts to squirm when they think about a real person becoming upset with them.

When those around you talk about the abstract concept of “users” or “customers”, try to bring up specific real people whenever possible.

->8-

The entire post is well worth reading. I had to laugh a little at the thought of putting up pictures of users all over my office because I have a ton of pictures of my family all over my office. I will make room for some BMC Software users. Feel free to send me your picture.