just write click

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.

I attended the central Texas DITA users group meeting last night, and wanted to write up some notes. We had two speakers share their thoughts after attending two related conferences this spring.

Bob Beims from Freescale shared his thoughts on attending the DITA 2006 conference at North Carolina State in Raleigh, NC, the first conference of its kind. He thinks he heard there were 185 attendees, and was pleasantly surprised at the range of users he met there. People were from medical companies with products for nurses, from the financial industry, from power and electric companies, and there was the hardware and software crowd. He had a couple of great quotes from different sessions. How about: “This is not rocket science… it is really bow and arrow stuff that has been implemented with technology.” from Michael Priestly of IBM, or “there’s never enough time and money to do things right, but always enough time and money to do things twice!” from Bernard Aschwanden of Publishing Smarter. I personally liked “Take the leap (or fall off the cliff!)” from Bob himself.

Bob said he realized that DITA solves some topic orientation problems that our industry has faced for decades. He was pleased at the rate and pace at which the DITA Technical Committee is churning out releases… 1.1 due out soon, and 1.2 in the next nine months. He feels that the OASIS leadership proves that DITA is not “just an IBM thing.” He thinks DITA maps should be awarded innovation of the year. He said, if you hate the limitations of FrameMaker conditional text, you’ll love the future of DITA with key values ( DITA proposed feature #40) that would allow boolean queries against conditions for output. A conditional text tags contest ensued, with a starting bid of documents with 13 conditional text tags and finally someone with a Frame document with 39 conditional text markers won the contest. I appreciated his comments on the two strata of tools — either very expensive, very functional, and easy to use, or (almost) free, fairly functional, but you’d better be a gear head to use ‘em. He sees a definite lack in conversion helpers for legacy content. Of course, with those words, a lively discussion ensued about transforming content versus just getting the text out by converting. Nearly all those experienced in unstructured to structured conversion projects discover, a real human has to figure out how to make topics out of the text that comes from a conversion. People who had done conversions said that Perl on MIFs out of Frame does the trick for getting out text, but in some cases you’re better off starting from scratch to plan for reuse and true topic orientation. Still, a conversion script (or set of scripts) at least takes your existing text into a structured start. Bob also said that something he has learned while researching from many presentations inside and outside of the DITA conference is that you must develop an Information Architect role or you’ll end up chasing your tail when it comes to truly gaining benefit from a topic-oriented architecture for your information.

What does Bob see as next for DITA? He’d like to see a lower bar for entry. Currently the entry “fee” includes a lot of time for preparing your content and training your writers, skills necessary to participate are high, and there’s money required for a bat and ball. He thinks there can be integration with non-DITA XML information streams, especially for those who interface with manufacturing industries. His example from Freescales’ perspective was the RosettaNet effort, where hardware manufacturers can offer “product and detailed design information, including product change notices and product technical specifications” via XML specifications. Incorporating that with DITA topics would help them build their information deliverables. He also noted that the DITA community might be a small one, but it is definitely composed of bleeding edge technology and technologists.

Next, Paul Arellanes, an information architect at IBM, gave his impressions of the Content Management Strategies 2006 conference in San Francisco. He saw a definite eagerness to adopt and use the DITA Open ToolKit as well as eagerness to reuse, reuse, reuse. His talk, Taxonomy Creation and Subject Classification for DITA Topics was highly attended (standing room only) and very well received. He also stressed the importance of training on topic orientation before going to XML. He has a programming background, and likens DITA to object-oriented documentation. He’d like to see code reviews of how the tags are used and if they’re used correctly. He got a couple of good ideas at the conference for how to build code reviews into the document review cycle. I’ll talk about those in the next paragraph. Paul talked about reuse and asked if it’s a boon or a curse? Can you reuse a topic if you can’t find it? What if the topic was never designed for reuse in the first place? How can you design for reuse in the first place? He’d like some best practices for reuse.

He said that implementing DITA is a chance to change your documentation processes — going to topics with a fresh start at content is more successful than a legacy conversion due to being able to build and design for reuse. His takeaways are that we need best practices for reuse, he’d like to build in source code reviews, and found a cool method for doing that with an editor’s CSS process that checks syntax. These are the common errors that you could find and mark up with CSS (basically, colorcoding the output after running it through a syntax checker built on CSS). Often these types of syntax/markup errors happen because the writer is tagging for looks, not for meaning of the content, but it can also happen with legacy conversion.

• placement of index entries
• sections that should be separate topics
• use of definition lists to create sections
• ordered list tags instead of using step tags
• lists of parameters in ordered lit tags instead of param list
• use of unordered list tags with bold instead of definition list
• use of <ol> or <ul> instead of substeps or choices element in a task topic
• use of <filepath> for variables and terms
• menucascade not used
• uicontrol not used

Paul also has good ideas for the future, including a troubleshooting or problem analysis and determination specialization from the task topic, and perhaps a way to pull out DITA elements from a topic and plugging it into interactive content using AJAX. He was pleased to see that the skill set among attendees is pretty high, including XML, XSLT, SAX, FOP, CSS and Ant build tool skills.

Interestingly, as far as our group could see, Adobe was not represented at the DITA 2006 conference, even though they have a group implementing DITA for solutions documentation.

If you’re like me and didn’t attend the DITA 2006 conference, you might enjoy (as I did) the transcript of Norman Walsh’s talk. Norm is the chair of the DocBook Technical Committee, and DocBook and DITA are constantly pitted against each other for solving the problems of information developers.

I’ve been blogging since last September, believe it or not, with almost 75 posts to show for it. After talking it over with my peers and the web team and studying the content including the categories and trends for my content, I’ve decided to change the name of this blog to “Exploring Information Design and Development.”

My Bloglines subscription already picked it up, which is quite cool. It is probably time to re-import the talkbmc.opml file to get feeds for the new additions. Welcome all!

What can you do when expert content is hard to come by? I’m talking about the upper-crust trusted sources of technical information, much like how A-list bloggers are set to get the higher page rankings on certain topics. Even Technorati is allowing you to filter by authority now when you search for keywords. From the Technorati blog: “The new Filter By Authority slider makes it easy to refine a search and look for either a wider array of thoughts and opinions, or to narrow the search to only bloggers that have lots of other people linking to them.” So is there a shortcut to authority? No, but you can find ways to connect to authoritative content. Here are a couple of ideas.

So let’s say you’re a work-a-day humble tech writer and you haven’t yet made it to a high level of authority on a technical subject, but your users are constantly looking for higher-tech, higher-value documentation. What can you do? This blog post explores two ideas about expanding the sphere of collection when it comes to technical documentation. Look high and low and especially outside of the content owned by your company ,and you can find documentation that your users want and need. Both of these ideas are not mine originally, I just helped implement them technically. A former manager of mine gets all the credit for thinking creatively about technical documentation and jumping through the legal hoops to make it happen. Thanks, Mike!

The first idea I’ve presented at an STC Conference and published as an article at WritersUA. In a nutshell, it’s go to the companies that have products that your companies’ products integrate with, and talk to them about information sharing. I’m talking about single sourcing in a whole new way. You’re sourcing content from other companies, and giving other companies your source to integrate into their products. This concept is what the future of technical publications can look like, especially with XML-source standards such as DITA and Docbook to facilitate sharing. Although, in this case, unstructured FrameMaker was the source file. You can read the links to discover the details on converting that source to the output we needed.

In this case, the particular type of content we pursued was error messages — message text, explanation, and user response — for the major database vendors IBM, Oracle, Sybase, and SQL Server. The product our team was documenting at the time integrated with all these database vendors and often the product passed through the vendor error directly. Since Oracle (and all the others) had comprehensive error message documentation that was similarly structured, we asked for the source files and with some legal contract work, received them. Once we got the source content, I wrote up a process for transforming it all to structured XML, then wrote an XSLT transform that could work in the product itself, transforming the content on the fly, offering HTML that contained both the explanation for the error and what you could do to correct or workaround the error. Now that is expert content, directly from the vendors who create the error message.

The second idea I haven’t really written up yet, until now. Mike Wethington talked about it at the Region 5 conference in the fall of 2003. An email exchange with Cote and a post at his People Over Process blog prompted me to write it up here. The other place we sought out expert content was from O’Reilly, a well known and trusted technical book publisher. It was in the first year or so that Safari, the online book repository, was offering content using a subscription model. With much legal wrangling that I know little about, my manager and the BMC legal team wrote up a contract with O’Reilly book publishers to offer selected reference books in an online format for selected expert database products. The book titles were all Oracle-centered titles, and we selected books that we knew were popular sellers and contained the information that users of our database products would find helpful for both day-to-day tasks as well as future planning and fine-tuning tasks. For this particular product, we supplied a “teaser” set of content, letting the user know that O’Reilly books are available and giving an example of the content they would get if they purchased a permanent license. According to Cote, CITTIO claims they were the first product to integrate with Safari. That may well be, but we had a precursor to that, imbedding the content, shipping it with the product. They claim access to 3,300 books, and we just had eight. I’m not sure which implementation is the more usable, but I love that more and more expert technical content is being distributed and shared in these ways.

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.

Where I muse about personas and technical writing

It is exciting when something relevant to your job hits the mainstream news sources. In my case, Best Buy’s use of personas to help create empathy and understanding of customers was a concept I could relate to immediately. I want to share it with others who may not be familiar with technical writing and how we can use personas to help us write targeted end-user documentation. In this Washington Post article, I learned that Best Buy’s personas are:

• Buzz (the young tech enthusiast)
• Barry (the wealthy professional man)
• Ray (the family man)
• Jill (a soccer-mom type who is the main shopper for the family but usually avoids electronics stores).

The book that the Washington Post article references is “ Angel Customers and Demon Customers,” by Columbia University Professor Larry Selden. Apparently Best Buy would like to release the Demon Customers from their customer lists. I guess those demon customers are the people who buy-to-rent electronics, like buying an expensive scanner to scan one picture, and then returning it. Their Angel customers are someone like Jill, who rarely shops at the store but spends a lot when she does. I was curious to find out more about what they put in place to help target “Jills.” As it turns out, it’s better signage, special “escorted” assistance to fast checkout lanes, and places for her to hang out with the kids while they play the latest gadgets. I could go for all of that. I suppose I resemble a Jill in some ways, but in reality I’m such a tech enthusiast I’m probably a Buzz.

Personas aren’t meant to be a stereotype (I can empathize with the moms-who-go-to-soccer-games but don’t like the “soccer mom” label). Rather, personas should help you get a mental image of someone you’d like to help accomplish something. We’re not pigeonholing our users, rather, we’re trying to read like they would read and seek information like they would seek. Also, while you can keep a persona in mind while writing doc or designing a new product, you should be sure to accomodate people who learn or think in different ways.

At BMC, we have used personas in the past either for brand-new products or for a newly-acquired product where we want to be sure to understand the target audience. My favorite persona was a UNIX admin or DBA with 20 years of experience with long hair and a tie dyed t-shirt. He’s “Kip,” and he’s sleep-deprived, has wrinkled clothes, carries a pager, he’s an introvert by nature, a workaholic by habit and demand, a total tech junkie, he might feel a little ego-centric about name recognition and contribution, and he reads techy magazines online. There’s also “Kim.” She’s a junior DBA, just out of college, proud to be a DBA, goes to professional association meetings, she’s highly technical and professional but knows that she won’t be doing reorgs until she gains her coworkers’s trust. There are more personas used for different products, but that’s a sampling. You can use personas for writing doc or for designing a product.

One of the personas for writing that I always have in my head is my system administrator husband. He came home with a software user manual one night. He needed to refer to it because their VP had gotten a new BlackBerry and wanted their Exchange server to work with it. He didn’t need the manual for any other reason than the one-page of system requirements and the maybe two pages of configuration info. Other than those two types of info (reference info with a little bit of task info), he understood the product well enough from the interface alone to accomplish the task of setting up the VP with his new BlackBerry so he could receive his email off the Exchange server. This example sticks in my mind because the real task was getting two different technologies to work together.

How about you? Do you identify with any particular personas from Best Buy or BMC? Do you use personas while designing user assistance or a product or a service?