February 9, 2010

Collaboration – Writing is a Team Sport

Filed under: Uncategorized — heratech @ 10:00 pm
Tags: , ,

Collaborating over a laptopSeveral friends and I started a historical reenactment group last year. Since we are a new group, when we had our first encampment, I wrote up a recruitment flier to hand out to potential new members. I included a list of minimum kit: clothing, shoes, and personal items. I also listed the sort of people we were looking for: those who love history and are willing to work with the general public (especially children). Then I sent the draft out to a couple of our founding members for comments. And Alena wrote back that while I’d listed what potential members would do for the Guild, I’d forgotten to list what the Guild could do for potential members. D’oh! I quickly added a “Benefits of Membership” section to the flier. This wasn’t the first time that Alena had made suggestions that improved my writing.

The popular image of a writer has them hunched over a typewriter in some lonely garret, toiling over their manuscript without any human contact. But that image of the lone writer is a myth. Writers work with other people all the time. If you’ve ever read the Acknowledgements section of a book, the author almost always thanks an entire team of people who helped make their work possible. Chief among the people thanked is often their editor.

At my first technical writing job I was lucky enough to work with a fantastic editor, Paul Dixon. I was fresh out of my TW certificate program, and the only editor I’d worked with until that point was Judy Tarutz, who had volunteered her time to perform an editing pass on the students’ major projects. Working with Paul was a great learning experience. He covered my drafts in blue, green, or purple ink (he avoided red) writing comments, questions, and suggestions in the margins. Answering his questions forced me to reexamine choices or assumptions I’d made, revise poorly written sentences, and delve deeper into the product to expand my understanding. My second drafts were always improved by his edits. The seven years that we worked together helped shape me into the technical writer that I am today.

Some of the writers on our team resisted being edited. Some didn’t want to give up their love affair with the passive voice. And I think that others confused criticism of their draft with criticism of them as a person. It takes a strong sense of self to accept criticism of your work without taking it personally. I find that adopting the attitude that all feedback is for the good of the customer and documentation helps make criticism easier to accept. You need to step back from your writing and humbly accept the feedback that others are offering you.

Are you open to collaboration? Do you collaborate with your subject matter experts on what should be included in the product documentation? Do you work closely with an editor during developmental edits? Do you read test cases to get ideas for customer workflows? Do you tag team with other writers on your team? Do you work with your sales or marketing or training departments to coordinate the public facing documents in your company?

And if you don’t, why not?

My company recently hired a course developer/trainer. I recommended a former coworker of mine that I knew had recently been laid off. I was delighted when we hired him, since I had always tried to work with the training department when we worked together. I’m really looking forward to being able to collaborate with Herb as the work he’s doing interviewing our SMEs will also help me to fill in the holes in my documentation set. We’ll both be working on standardizing the terminology that we use to discuss the product, components, and processes. And when he starts building course modules, I’ll be one of his beta readers. I’m excited that I will no longer be the only person writing content for customers. Having a partner in crime gives us the potential to harness the synergy of collaboration.

Writing is a team sport. Who are your collaboration partners?

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?

January 6, 2010

Agile Tenet #8 – Sustainable Pace

Filed under: Uncategorized — heratech @ 11:09 pm
Tags: , , ,

Magic 8 Ball Eighth 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.


Agile processes promote sustainable development. The sponsors, developers, and users should be able to maintain a constant pace indefinitely. [emphasis mine]

Ah, a constant pace. Technical writers aren’t used to that. At least not in a Waterfall development environment. Waterfall technical writers are used to a significant amount of slack time at the beginning of the production cycle, then a stretch of regular work while coding continues, followed by a frantic scramble, often involving overtime, at the end of the production cycle.

One of the big disadvantages I can see to adopting Agile Sprints is that TWs lose the slack time at the beginning of the development cycle. I don’t know a single writer that has enough time to accomplish everything that they’re expected to do. Writers often use that beginning-of-the-cycle down time to catch up on projects that are important but not urgent, like researching writing tools, evaluating documentation processes, designing templates or style sheets, developing style guides, or just plain catching up on everything they didn’t finish in the rush to release. And heaven forbid you need to convert a large legacy documentation set to either a new tool or a new process. How on earth do Agile writers find time for big projects like adopting DITA? The short Sprint timeline makes taking time away from writing for things like conferences, training, and a well-earned vacation a little harder to plan.

Or maybe I’m still making the mental adjustment from being a member of a documentation team to being a sole writer. Even though it’s been a few years, it still feels weird to realize that I am the entire team now. And that if something needs to be done, there isn’t anyone but me make sure that happens.

One of the clear benefits I can see to adopting Agile Sprints is they eliminate that last-minute documentation rush at the end of the release cycle. Or if the scramble isn’t completely eliminated, at least the stress is spread around a bit more evenly so it doesn’t feel so bad. I can really embrace the idea of working at a steady pace.

But I keep bumping up against my fears about who gets to define what a “steady pace” is and whether or not my own personal, idiosyncratic writing style can be made to fit into the Agile mode. What about when I have writer’s block? (Yes, even technical writers get writer’s block.) There are days when the words just don’t flow. This is one of the reasons why I usually have a couple of side projects going at any time. If I can’t get my writing mojo to work, I can switch over and do some training, work on my glossary of product terminology, do some indexing, or spend time trawling the network/wiki for other useful documents that no one thought to forward to the writer. But those side projects, while productive, are not usually the sort of things that would fit neatly into a user story. Thus my anxiety about keeping up a steady pace of work.

Thinking and writing about this tenet reveals my anxiety that Agile is about forcing me to become more productive, ever increasingly more productive. I’m not a slacker by any means. At least not when I compared my production to the other writers when I worked in a doc group. And when I compare my page count from one year’s work to my estimates for what I should have been able to produce (based on the Dependency Calculator), I’m cruising right along. So why do I always feel like business is never happy with a productive employee and always wants more work (and for less pay)? And that no matter how hard I work, it will never be good enough?

Or maybe I’m just feeling uncomfortable about admitting to non-technical writers that the majority of my time is not spent writing, but on other activities? There is this misconception that all writers do is write. Judging from the number of writers blogs I read (both literary and technical writers) most writers spend less than half their time actually writing. Most non-writers don’t understand that all that non-writing contributes to the writing. And that “doing research” is not code for “farting around on the internet.” At least, not usually.

Or maybe I’m dealing with my own attempts at sustaining a constant pace of posting to this blog. And I’m finding that despite my huge list of ideas for possible posts, some weeks it is easier to generate three posts and other weeks it is a bit of a struggle. Of course, the only person requiring me to post three times a week is me. And perhaps the whole point of this post was to get me to realize that the person who has the highest expectations for my work is not my employer, but me. And that I need to give myself permission to find my own sustainable pace.

January 4, 2010

Agile Tenet #7 – Usable Doc as a Measure of Progress

Filed under: Uncategorized — heratech @ 8:35 pm
Tags: , , , ,

Seven Key Seventh 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.


Working software is the primary measure of progress.

Technical writers write documentation rather than software, so this is one of the tenets that needs to be slightly modified to apply to TWs. The question is, how do you define “working documentation” and whether or not the Agile technical writer is making progress?

We don’t want to use page count as a measure of progress. Lengthy docs often lack focus. Mark Twain said, “I didn’t have time to write a short letter, so I wrote a long one instead.” And Cicero, T.S. Eliot, Ernest Hemingway, Samuel Johnson, Blaise Pascal, George Bernard Shaw, and Voltaire have similar quotations about lengthy writing being an indication that they did not have time to do their best. Page counts are not a metric of good writing, in fact, if you localize, a low page count (and lower cost) is the goal.

Tightening up your writing can be as simple as changing “Click on the Save button” to “Click Save” which says essentially the same thing but takes less time to read (and if you’re localizing, saves you three words). But I’ve also seen people take brevity to extremes in an effort to reduce localizations costs. At one point during a cost cutting effort one of our executives found a company that promised to cut our word count by 40%. We sent them samples, but what came back was so spare as to be almost useless. If you’re only focused on word count or page count, you’ve lost sight of your users and meeting their needs.

Since tenet #9 is attention to Excellence, I believe that the measure of progress for a technical writer should be useful documentation. A couple of years ago I encountered the book Developing Quality Technical Information: A Handbook for Writers and Editors. I was so impressed with their definition of quality technical writing that I typed it up and posted it on the wall of my cube. Slightly paraphrased, their criteria are as follows:

Easy to use
Task Orientation Focused on helping users perform tasks related to their jobs.
Accuracy Free of mistakes and errors.
Completeness Includes all the necessary information, and only necessary information.
Easy to understand
Clarity Presents the information so that users understand it the first time.
Concreteness Includes appropriate examples, scenarios, specific language and graphics.
Style Appropriate writing conventions, words, and phrases.
Easy to find
Organization Arranging the parts in a way that makes sense to the user.
Retrievability Presentation that allows users to find information quickly and easily.
Visual Effectiveness Appropriate use of layout, illustrations, color, typography, etc.

I believe that one of the most important things you can do to make software documentation useful is to focus on the user’s task. Several years ago I took a community college course to learn how to use Photoshop. Our instructor chose the Photoshop Visual Quickstart Guide from PeachPit Press as our text. Both the course and the text were feature oriented rather than task oriented. As we worked our way through the many features of Photoshop I remember constantly wondering “But what would I use this for?” At the end of the semester we hadn’t covered what I suspect are the two most common corrections to photographs: removing red-eye and “correcting” skin blemishes. I could probably figure out which features to use, but it would have been helpful if the course and text had focused on common tasks.

Journalists seek to answer the Five Ws: Who? What? When? Where? Why? And How? I believe that useful documentation should seek to answer the same questions.

Useful documentation is the primary measure of progress for a technical writer.

December 14, 2009

Adopting or Adapting Agile

Filed under: Uncategorized — heratech @ 11:07 pm
Tags: ,

I’ve decided to change the tagline for my blog to “Adapting Agile to the ancient art of Technical Writing.” It’s a small change, only one word, from “applying” to “adapting.”

Since I started this blog a couple of weeks ago, I’ve been doing some heavy-duty thinking about everything that I’ve read and learned about Agile in the past year. Agile is a process that was designed to address the pain points of developers, not the pain points of technical writers. And I keep coming back to the same thing, TWs are not developers. And I’m not convinced that writing code and writing documentation have all that much in common.

Agile has the stated claim of reducing documentation. But technical writers have a vested interest in documentation, as that is one of our primary functions in the organization. Of course, when Agile practitioners say “documentation” they are referring to requirements, design documents, functional specs, and other product documentation. When technical writers say “documentation” they’re referring to installation guides, user manuals, online Help and other user documentation. (I supposed I should get used to calling what I write “user assistance” but I’m so used to calling it “documentation” it’s hard to make the mental shift.)

Technical writers don’t have a choice of whether or not to “go Agile.” If our development team adopts Agile practices, then we have to follow along or fall behind. Thus, the more I think about it, this blog is not so much about adopting Agile “as is”, but about figuring out how it can be adapted to better meet the needs of technical writers.

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.

Blog at WordPress.com.