January 24, 2010

To Assume makes an Ass out of U and Me

Filed under: Uncategorized — heratech @ 11:55 am
Tags: , , ,

Confused computer userWhen I was a High School English teacher I taught The King Must Die, the story of mythical Greek hero Theseus, to my freshmen. My students told me that they had studied mythology in Middle School, so I assumed that they had some frame of reference for reading a novel set in ancient Greece and Crete. I was surprised when, during a class discussion, one of the students asked why the hero was walking everywhere. “Why doesn’t he just drive?” I hadn’t thought that I’d have to explain to my class that cars didn’t exist 3000 years ago.

I’ve been thinking about assumptions this week. I just returned from my holiday visit with my parents. (Since I waited too long to book my Christmas trip it turned into a belated Twelfth Night trip instead.) While I have known for years that my mother is computer illiterate, I had assumed that she at least had some basic keyboarding experience. My father worked for IBM and then Lexmark, so we’ve always had typewriters and computers in the house. But it turns out that my mother hasn’t touched a typewriter in 30 or 40 years. So when I was talking her through the process of logging onto her e-mail account, I had to explain how to use the SHIFT key to get the @ sign in her e-mail address. Sitting with her and watching her struggle to learn how to double-click a mouse and click and drag the scroll bars was a bit of a revelation. At one point she turned to me and asked, “How did you ever learn all this?” And that question has haunted me all week.

At my first technical writing job we assumed that if you were a system administrator that you were probably an experienced computer user, possibly with a computer science degree. We also assumed that our Support folks just liked to complain about how clueless our users were. That is, until the doc team conducted a survey at our annual user conference to learn more about the audience for our documentation. We were surprised at the large number of people who said that their job title was “system administrator” who also described their computer experience as “novice” or “intermediate.” No wonder they were having troubles!

I used to rely on my developers opinions on whether information should be included in the documentation. But too often I would come across some concept that was unfamiliar to me, spend the time researching and writing an overview, only to be told that “Our customers would know that.” Really, would they? As I gained more confidence in my own ability to understand users, I stopped relying on my SME’s opinions about what users would know. Developers tend to be too familiar with computers and coding to have any idea of what it is like to be a typical computer user. They forget that the majority of computer users do not have computer science degrees, and consider computers to be more mysterious than logical.

When I got back to the office after visiting my parents, I started looking at our product and my documentation with new eyes. What assumptions are we making about our customers? And are there any simple steps we can take to help make the user experience better for our customers?

For example, when our UI designer at a previous company first introduced the unlabeled “Select All” check box, I complained that users wouldn’t know what it was for. “But it’s just like Yahoo Mail.” he said. But I didn’t use Yahoo Mail, I used AOL, so I’d never seen this feature before.
Select All Check Box

AOL has since adopted this check box, but their version doesn’t have a label either. How much effort would it take to add a tool tip (hover text) to label this check box “Select All”? Why do we assume that users will know how to use features if we don’t explain what they are for? Or even worse, if we don’t even label them?

When I write, I tend to put myself in the user’s shoes and ask “What would *I* expect to find in the documentation? What questions would I have about this product?” I’m a bright person, so if I find something confusing, I assume that our users might find it confusing too. Yes, I’m making assumptions about our users, but I’d like to think that my users appreciate the fact that I’d rather assume they might need information than to assume that they already know it. Isn’t conveying information what good technical writing is all about?

If I include information that a user doesn’t need, they can easily skip over it. For example, when I use Google Maps, I don’t really need to know how to get out of my driveway and onto the highway. I skim through the first several steps in the directions until I get to the first major highway and follow the directions from there. And on the return trip, once I’ve arrived on a familiar road I abandon the directions.

What assumptions are you making about your users? And what simple changes can you make that will benefit your users?

December 23, 2009

Agile Tenet #4 – Work Together Daily

Filed under: Uncategorized — heratech @ 7:39 am
Tags: , ,

Four hands Fourth in a series of posts examining the Twelve Principles of Agile Software and how each of these tenets can (or can’t) be applied or adapted to technical writing.


Business people and developers must work together daily throughout the project.

When I was studying for my technical writing certificate, one of the things that my writing instructor emphasized was to know your audience. I want as much information as possible about my customers and their tasks so that I can write documentation that meets their needs. At my first technical writing job that was a bit of a challenge. The company made a highly configurable product for managing assets and work orders that was marketed to a wide variety of different industries. Our customers fell into four main categories:

  • Manufacturing and utilities production
  • Hotels, universities, and other facilities
  • Buses, trains, aircraft, and other fleet vehicles
  • Information technology (IT) assets
  • As you can imagine, this created a bit of a challenge for the writing team. Our customers could be virtually anyone.

    In the years that I was employed there I worked hard to gather information about our customers. The company sponsored an annual User Group conference that was well attended. Unfortunately, when they were picking the employees who would attend, the Powers That Be favored product managers, support, and quality assurance engineers, and not technical writers. One year we managed to send both doc managers, who conducted a customer survey and hosted a documentation discussion that they taped and played for the team at one of our department meetings.

    Since I couldn’t attend the user group, I decided to find other avenues for face-to-face contact with our customers. I started working closely with our training department. I made friends with some of our trainers and course developers over lunches in the company cafeteria. As a result, they started inviting me to sit in on beta training for new courses, since I could provide feedback to the course developers. I also made an effort to attend our customer training courses at least once or twice a year. I always paid close attention to the scenarios that the trainers were using to present our product, and listened to the questions that our customers asked. And our customers often asked a lot of detailed questions, trying to squeeze some free consulting out of our trainers.

    In my final year at that company I worked on a specialized part of the product, and my manager was finally able to get me on the list for our User Group conference. I spent four days on the floor, demonstrating the product in our Demo area and answering customer questions about new features. I also was able to attend a few of the customer presentations, and was fascinated by the different and creative ways that our customers were using the product. As a result of meeting the moderator at the conference, I was also able to join the heavily moderated, customers-only Yahoo group for our product, which gave me even more insight into our customers.

    I left that job for another one, working for a smaller company whose product was in the same space. I had much more customer contact at my second TW job, attending a User Group conference in my third week on the job. At that job I was a Lone Writer, and as a result I wore many more hats. During the year and a half that I worked for that company, I attended three different User Groups, assisted one of our consultants with an implementation at a customer site, and taught one session of user training.

    At my current job I’m back to having limited information about our customers, and the product owner for our teams is the VP of Engineering. I’m back to brainstorming ways to learn about our customers. I’ve been getting to know our support team. And we just hired a trainer, someone who I know from a previous job and with whom I already have a good working relationship.

    Just as I was getting ready to write this post, one of Mike Cottmeyer’s Interesting Links posts let me to a post about how Agile isn’t designed to meet the needs of customers. This makes me wonder, despite the stated goal of involving customers in the development process, how much actual customer contact I can expect in an Agile environment?

    I think we should make a slight revision to the wording of this tenet, from “developers” to “teams” so that it includes technical writers, testers and other team members.

    Business people and teams must work together daily throughout the project.

    December 18, 2009

    Agile Tenet #2 – Welcome Changing Requirements

    Filed under: Uncategorized — heratech @ 11:12 am
    Tags: ,

    Two fingers, V for victory Second in a series of posts examining the Twelve Principles of Agile Software and how each of these tenets can (or can’t) be applied or adapted to technical writing.


    Welcome changing requirements, even late in development. Agile processes harness change for the customer’s competitive advantage.

    Early in my TW career a product manager changed a toolbar icon a week before a release. I updated the User’s Guide to reflect the new icon. A day before the release he changed his mind, and reverted back to the original icon, but didn’t tell the doc group. Luckily it was a beta release, so the incorrect docs only impacted a single customer.

    While technical writers may not actually welcome change, most of us have had to adapt to the reality that developers often make changes the software and forget to tell us. Getting TWs to welcome change? Well, that may require a major attitude adjustment for some of us, as whingeing about how we get no respect is as much a part our perception of our jobs as it was part of Rodney Dangerfield’s comic persona. Many of us spend our days trying to earn that respect by subtly reminding our coworkers that we provide customer value too.

    I think that part of the value of a technical writer is often found in the types of questions that they ask about the products that they document. When I was first investigating technical writing as a career change I attended an information session for a TW certificate course. The speaker was a graduate of the program whose previous career had been as a journalist. I remember that he said that his new career was much like his old career; he still spent his days interviewing people, then going back to his desk and writing. Ever since then I’ve looked at my work as a form of investigative reporting.

    For example, if the new feature is to allow the user to create or change a password, I might ask the following questions:

    • Can the password match the user name?
    • Are there any length requirements or restrictions for the password?
    • Is the password case-sensitive?
    • Are there any requirements for the first character in the password?
    • What special characters are allowed in the password?
    • Does the password expire?
    • Can you reuse passwords or partial passwords?

    When would it be more helpful to the project to have the technical writer ask these questions? Would you rather have them ask the developer after the code is complete, or ask the customer or product owner during the Sprint planning process, while you’re writing the acceptance criteria for the User Stories?

    Agile processes harness change for the customer’s competitive advantage.

    So not only do TWs need to welcome change, we need to figure out how to harness it for our customers. I think one of the ways that we can do this is to keep up with the changes in technology and how information is shared in the Internet age. There are many new options for delivering content to our users. Yesterday my former manager sent me a link to the documentation Wiki that he’s working on. And there has been a brief discussion on the TECHWR-L mailing list recently about using WordPress as a documentation platform. I’m still waiting for my copy of Anne Gentle’s Conversation and Community: The Social Web for Documentation to arrive. I’m looking forward to finding more good tips for harnessing Web 2.0 for my customers in her book.

    This tenet ties into one of the core TW goals, to understand users and their tasks so that we can write useful documentation. I think the trick for the Agile team is finding the right balance between understanding the user’s requirements and reducing project documentation so that you can get down to the business of creating the product. Technical writers, with our user focus, can help our teams remember that the goal is to meet our users’ needs, not just deliver working software.

    December 11, 2009

    Keeping Close to Users – Everyone Should be Tech Support for Someone

    Filed under: Uncategorized — heratech @ 8:48 am
    Tags: ,

    Help Desk signDuring this holiday season, I know that many of you will be facing phone calls from friends and family who assume that because we work in the industry, that they can call on us at any time for technical support. Rather than be frustrated with our loved ones and resentful of their assumptions, this year I’d like to suggest that you try to see those family tech support calls as a Good Thing.

    Everyone involved in creating hardware, software, and documentation needs to remember what it is like to be a new user. Those requests for help are your chance to keep in touch with novice users and observe their struggles to learn new technologies. So as you help Great Aunt Ruthie figure out how to program your phone number into her new cell phone, remember to observe and take mental notes.

    How do novice users react to new technology? Do they dive right in and start playing? Or, like my mother and the laptop that she bought last summer but hasn’t taken out of the box yet, are they hesitant to move forward without an experienced user to guide the way?

    Do users know that online Help is available? Do they read the manual? Last year my father bought a new cell phone two days before a family vacation. He spent the whole trip playing with it, learning the new features. At some point he was cursing at it, and I gave him The Eyebrow and suggested that just maybe, since his daughter is a technical writer, he might consider reading the manual? He said that he’d rather play with it and figure it out for himself. *sighs* Thanks Dad, love you too.

    Do users only go to the documentation when they’re stuck? When I bought my first laptop, before I had high-speed internet, I spent two days trying to figure out why I couldn’t get on the internet with my phone modem. Finally, after getting thoroughly frustrated, I decided to check the manual, only to find that I’d been plugging the phone cord into the network port by mistake. Oopsie. Ever since them I’ve been much better about reviewing the documentation when I buy new products.

    When users do consult the documentation, how do they search for information? Do they use the Table of Contents, the index, or the search feature? Conventional wisdom in the TW community seems to be that users do not use indexes, and it has fallen out of fashion in the industry. (Microsoft, I’m looking at you.) I am a fan of indexing however, and I suspect that if users truly have abandoned indexes, it is because we have done such a bad job of constructing them. Most indexes are woefully short, and often don’t contain the most common terms for features. For example, I have a digital camera and wanted to find out if it has a timer feature that would let me take pictures of myself. I searched the index for various keywords, delay, timer, etc. I finally resorted to reading the entire index, only to find the feature listed under self-timer, a term I never would have searched for.

    Is the documentation adequate to the user’s level of experience? I’ve been tackling a few home improvement projects around the house lately. Last weekend I was attempting to install new towel rods in the bathroom, but found the rather short instructions on the package inadequate. The instructions assumed previous experience with home improvement and tools, which I do not have. I could not successfully install my new towel rods using the provided instructions.

    Can users find what they’re looking for in the documentation? Or do they have to resort to Google or an experienced user to answer their questions? In order to successfully hang my towel rods I had to read through a couple of different home improvement and do-it-yourself Web sites before I found clear instructions appropriate to my novice-level handyman skills.

    This holiday season I’ll be headed down to visit my parents, where I will be assisting my mother with that new laptop. Mom is computer illiterate, but last summer when my father was off on his annual motorcycle trip she bought herself a laptop “because it was on sale.” I understand why she hasn’t asked my father, a retired mechanical engineer, for help. This is the man who taught me how to drive a car by pulling out the encyclopedia and having me read the section about manual transmissions. Like many engineers, he’s highly educated and can’t remember what it is like to be unfamiliar with technology. Since I try to roleplay novice users when I’m writing, I am happy to help mom. It should be an educational experience for both of us.

    Create a free website or blog at WordPress.com.