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 15, 2010

Agile Tenet #10 – Simplicity is Essential

Filed under: Uncategorized — heratech @ 3:23 pm
Tags: ,

Jersey number ten Tenth 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.


Simplicity–the art of maximizing the amount of work not done–is essential.

When I was a child I read Cheaper by the Dozen by Frank and Ernestine Gilbreth. Their parents were the pioneering industrial engineers and motion study experts Frank Bunker Gilbreth and Lillian Moller Gilbreth. I still remember one of the opening descriptions of their father:

…at home or on the job, Dad was always the efficiency expert. He buttoned his vest from the bottom up, instead of from the top down, because the bottom-to-top process took him only three seconds, while the top-to-bottom too seven. He even used two shaving brushes to lather his face, because he found that by doing so he could cut seventeen seconds off his shaving time. For a while he tried shaving with two razors, but he finally gave that up.

“I can save forty-four seconds,” he grumbled, “but I wasted two minutes this morning putting this bandage on my throat.”

It wasn’t the slashed throat that really bothered him. It was the two minutes.

I re-read the book several times as a child. Probably because my father was an engineer, and I could see Mr. Gilbreth as a slightly more charming version of my father. And I have to say that those repeated readings had an effect on me, instilling me with a bit of a secret desire to be an efficiency expert. When I think about “maximizing the amount of work not done” I always think of Mr. Gilbreth.

This tenet focuses on one of the cornerstones of efficiency – the KISS principle: Keep it Simple, Stupid. This is such a key concept, and yet, so often people forget it. Don’t make extra work for yourself. Find the simplest solution possible to problems. Work smarter, not harder.

Some of the ways that I like to keep things simple include:

  • Using styles and templates. Over the years, I’ve always been surprised at the number of people (including the occasional technical writer) that don’t use styles to format their documents, especially Word documents. The first thing I do when I start working with an authoring tool or a document is inspect the template. Knowing what styles are available saves time when it comes to thinking about how I want to arrange the information that I’m writing. When I’m the one creating the templates (which I’ve done in both FrameMaker and Flare) I first create a basic set of styles, then add to them as needed. When I’m dealing with an overly complex FrameMaker template, I’ll delete the styles that I don’t need. I can always import them back into the document if the need arises.
  • Writing short, simple modular content that is chunked into concept, task, and reference topics. Chunking content into smaller pieces makes it easier to add, remove, and rearrange content as needed. It also reduces the amount of content that users need to scan to find information within a topic.
  • I try to avoid overly complex branching procedures because I find them confusing. I assume that my users would find them confusing too. I try to write short, simple procedures. If a procedure becomes long and involved, try to break it into smaller procedures.
  • Don’t reinvent the wheel. Especially when it comes to something like Style Guides. Pick one of the major style guides (Apple, Chicago, Microsoft, Sun, Xerox) and only document where you differ from it. As a lone writer I don’t have time to write my own in-house style guide. I use the Microsoft Manual of Style (partly because Microsoft is so ubiquitous that it feels familiar to most people, and partly because I can always find a copy on the shelf at my local Barnes and Nobles).
  • Probably the most important way to maximize the amount of work not done is not to include information that the customer doesn’t really need in your documentation. Always keep the customer and their tasks in mind. Sometimes that means that you have to trust your own judgment over that of your developers as to what the user needs to know. Yes, the developer thinks that customers need to know the algorithms and all the other little details about how the software does its thing. But chances are, your customers really don’t need or want that level of detail about how things work. They assume that when they click the button, it will do what it’s supposed to do. You don’t need to be a mechanic to drive a car, and most users don’t need to know the inner workings of software to be able to use it.

Simplicity is essential. Work smarter, not harder.

January 11, 2010

Agile Tenet #9 – Attention to Excellence

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

Area nine. Ninth 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.


Continuous attention to technical excellence and good design enhances agility.

I met Abby Fichtner at the Nashua Scrum Club. Her card included the address of her blog, the Hacker Chick, and since like the elephant’s child I have an insatiable curiosity, when I got home I surfed on over to check out what she writes about. She’s got some great posts over there. I particularly like this one about Craftsmanship where she states that one of the most important lessons of Agile is “the only way to go fast is to go well.”

“How many times have you been significantly slowed down by bad code? Martin asks and we can be sure all programmer hands went up. “Then why did you write it?” he asks. There is laughter because of the truth in his question. We have all been slowed by bad code and yet, we continue to allow bad code to be written on our projects. And why? Because we didn’t have time to write it well?”

“We must not write bad code. Period. This is a fundamental issue of professional behavior.”
– Bob Martin

As I’ve been learning about Agile, there seems to be quite a bit of emphasis on not just delivering software, but delivering better software. When we started our move to Agile at my company, there was a lot of emphasis on testing, with added unit tests, test harnesses, test plans, etc. I’m not sure if we meet all the requirements for test driven development, but we’re probably pretty close. Which means that our next release is going to be of significantly higher quality than our last one. This is good news for our customers, and will hopefully translate into better word of mouth and better sales. I appreciate that the Agile emphasis on speed does not mean that we’re producing sloppy work, but also focusing on quality product.

Abby’s post on Craftsmanship led me to this one where she writes:

“And I just keep thinking back to Clean Code’s preface: if we’re to call ourselves professionals, we have a responsibility to act as such. And maybe that means we really do need a 5th element for our Agile Manifesto: We value Craftsmanship over Crap.

So, how do you adopt this tenet to Agile technical writing? As Agile TWs we need to figure out how to not only write faster, but how to write better. And I’ve been lucky enough to have been exposed to automated tools that can help you be a better writer.

At a previous job we were implementing a pilot program with acrolix acrocheck (which seems to have been replaced by acrolinx IQ) a style and grammar tool that was designed to reduce translation costs. The tool had a number of different features: it checked spelling and grammar, checked a variety of common style rules (as defined in the more popular style guides), and could be programmed to check for in-house terminology and style. You could also use it with Microsoft Word, Adobe FrameMaker, and RoboHelp. Part of our pilot program was figuring which rules we wanted to keep and which we were going to disable. For example, our product had a Users application, so we had to decide if we were going to keep the rule “don’t use the word user in your documentation.”

I’d always thought I was a pretty good writer, but the first time I ran the tool against one of my projects, I was absolutely horrified by how many errors were flagged in my document. It’s a good thing that my attitude towards editing is that is necessary for improvement, or I’d probably have been curled up under my desk. My three most common errors were sentence length, future tense, and passive voice, but there were plenty of other problems. Most of them easily fixed.

I used acrocheck for at least three months as part of our pilot. And one of the things that I noticed was that it was starting to improve my writing, in much the same way that using spell check consistently finally teaches my fingers the correct spellings of words that I initially misspell. I was starting to catch myself using passive voice during my writing process, before I ran the tool against my draft. I also started noticing when my sentences were creeping towards run-on (although, as you may have noticed, it’s still a problem I struggle with!).

The acrolix product is enterprise level, and priced accordingly. Not something that I’m likely to be able to access in my new role as Lone Writer. But if you’re a FrameMaker user, I’ll point you towards the download for SDL Author Assist a FREE grammar and style checking tool. I’ve played with it, and it is worth the upgrade if you’re not yet on FrameMaker 9.

If we’re going to call ourselves professionals, we have a responsibility to act as such. We value craftsmanship over crap.

I love this. This resonates so profoundly with me. This just may be my new motto.


Here is another post on the fifth element for the Agile Manifesto – Craftsmanship over Execution. Read through the comments, they’re great.

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.

January 3, 2010

My Not New Year’s Resolutions

Filed under: Uncategorized — heratech @ 2:14 pm
Tags: ,

New Year's Resolutions At the end of every year I like to reflect on where I’ve been, and make plans for the coming year as I break in my new calendars. Over the past couple of years I’ve moved away from New Year’s Resolutions (which are made only to be broken) and toward setting goals for the coming year. As I was considering my professional goals for 2010, I kept coming back to Stephen Covey’s Seven Habits of Highly Effective People, which I first encountered back in 1998 when a friend gifted me with a Franklin Covey organizer. Being a biblioholic, I had to purchase the book too.

Covey’s Third Habit is “Put First Things First” and addresses time management. His simple little Time Management Matrix, solves the mystery of why you never seem to be able to accomplish those New Year’s Resolutions. All that self-improvement you resolve to take on falls into Quadrant Two on his matrix, where activities that are important but not urgent reside. If you don’t schedule time, they never seem to get done. At the moment I’m only working part-time, and even though there has been mention of adding a fourth day to my schedule this winter, that still leaves me at least one free day a week. I do not have the excuse of being “too busy” to keep me from accomplishing at least some of the goals on my 2010 list.

I’m an avid reader, so it’s no surprise that the first item on my list is finishing some work related reading. Some of these books are recent purchases, others have been waiting patiently for me to get to them for some time.

1. Conversation and Community: The Social Web for Documentation by Anne Gentle
2. Managing Writers:a Real World Guide to Managing Technical Documentation by Richard Hamilton
3. User Stories Applied For Agile Software Development by Mike Cohn
4. Do It Yourself Agile by Damon Poole
5. Lean Software Development: An Agile Toolkit by Mary and Tom Poppendieck
6. Managing Enterprise Content: A Unified Content Strategy by Anne Rockley
(And since it’s on my mind, I’ve pulled out my copy of the Seven Habits of Highly Effective People for a re-read.)

At my last job I was using Madcap Flare. I spent two days with CSS The Missing Manual and was able to create a usable template. But I want a little bit more experience before I feel comfortable adding CSS to the skills I list on my resume. So another goal is to spend some time learning more about cascading style sheets this year. It’s also a skill that I’ll be able to use as Web mistress for my reenactment group’s Web site. (I love when I can kill two birds with one stone.)

Another goal for 2010 is to continue to build my professional network. I’ve gotten every single one of my technical writing jobs through networking. When I was an intern the woman sitting in the next cubicle was good friends with a doc manager who was building a department and suggested I send her my resume. My next job came when a former co-worker called to inform me that he’s lined up an interview for me. I found my current job when one of my coworkers notified her social network that the company was hiring. We have mutual friends, who passed along the opportunity. I’ve also been able to pass along the favor and helped two fellow TWs and a trainer find positions. [Before you dash off and send me an invitation on LinkedIn, you should know that I am a very conservative turtle, and only link to people who I 1) know personally, and 2) would feel comfortable recommending for a position.]

In 2010 I plan to attend more STC meetings than I did in 2009. I live in an area that gives me access to both the Boston and New England chapter meetings. I will also continue to attend the monthly meetings of the Nashua Scrum Club as often as possible. And I’ve recently joined The Agile Bazaar, and signed up to attend their next event.

I’d also like to attend at least one professional conference this year. I’m disappointed that our local conference promoter has fallen victim to the economic downturn, as I don’t often have both the time and the budget to travel. I’ll be keeping an eye out for technical writing or Agile conferences in the Boston area. If you know of any, please leave a comment.

I also plan to continue to blog in 2010. Even though I started HeraTech less than two months ago, I’ve found that being forced to think about my work, sort through my experiences, look at what I’ve been reading, and consider some of the big issues for Agile technical writers has been a beneficial experience. It will also be the nudge I need to accomplish my other goals, as I need to “feed the blog.”

What are your professional development goals for 2010?

December 28, 2009

Agile Tenet #6– Face-to-face Communication

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

Six elephants Sixth 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.


The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.

There have been many times when I’ve sent an e-mail to a Subject Matter Expert and asked, “Does it work like this, or like that?” And have received back a terse answer of “Yes.” Argh! Which usually leads to me tracking down the SME in his lair and asking, in person, does that answer mean “Yes it works like this” or “Yes it works like that.”

The short trek to Developer Land is often worth the effort, as most of the developers I know would rather talk about what they’re doing than write about it. (Or occasionally draw about it, my VP loves to scribble on his white board.) So I get much more information out of a conversation that I would from an e-mail or a specification. The conversations often lead to me gaining information that I wouldn’t have thought to ask about in the first place. And I also get the opportunity to ask questions, instantly clarifying points that I don’t understand.

Despite how useful face-to-face communication can be, it is not the first thing that I rely on when I’m doing research. I am a reader, and a fast reader at that. So I try to do my homework before I go to a product manager or developer with questions. If I can answer a question by myself, I don’t want to bother someone else. And I’ve found that doing as much advance research as I can, be that reading or experimenting with the software, helps me to focus my questions, and results in better answers. It saves time for both me and the person I’m interviewing.

Tenet 6 is one that has a huge impact on how technical writers do their work. With an emphasis on more face-to-face communication and less written communication, the writer has reduced access to specifications or even e-mail threads when they’re doing their research. If the writer is in the same physical location as the development team and the quality assurance team, that lack of project documentation can be made up with more face-to-face communication. But these days, off-shoring means that a lot of us don’t even work on the same continent as some of our team members. My first tech writing job had team members in Canada, Brazil, and India. My second had development in New Zealand and quality assurance in India. My current position has developers and QA in both India and China. I’m sure that there are those that would say that if team members aren’t all co-located that means we’re “not doing Agile.” But I suspect that most companies are in a similar position, with team members scattered all over the globe.

Which means the team needs to develop new skills for building and maintaining teams. At my previous job I used Skype to chat with my New Zealand developers on a regular basis. My current job has also experimented with using Skype and instant messaging with team members in China to bring them into the Scrum meetings one or two days a week. We have an internal Wiki, and there is a team page with everyone’s picture, and all of our contact information (e-mail, phone numbers, Skype and instant messaging IDs). Being able to put a face to a name helps you feel more connected to someone who you’ve never met.

I’m still making the transition from my old work habits to more Agile ones. As I work through the backlog of doc bugs and undocumented legacy features and start working on the new features, I know that my research will be quite a bit less reading and a lot more interviewing. I’ll be back to the journalism model where the writer is interviewing the SME. I’ll need to be proactive and get out of my office and talk to my team more than I’m used to. I’m pretty sure that I’m going to be handicapped by my six month absence from Scrum. I’ve missed a lot of design discussions, and without project documentation it’s going to be hard to catch up on what I’ve missed. It’s going to be a challenge. But this is one of the few areas where I’ve heard positive things from other Agile technical writers, so I know it is a challenge I can meet.

The most efficient and effective method of conveying information to and within a development team is face-to-face conversation. It is essential that the technical writer be considered a full team member and be included in these conversations.

December 24, 2009

Agile Tenet #5 – Motivated Individuals

Filed under: Uncategorized — heratech @ 9:43 am
Tags: ,

Five employees Fifth 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.


Build projects around motivated individuals. Give them the environment and support they need, and trust them to get the job done.

The part of this tenet that really resonates with me is trust them to get the job done. Abby Fichtner recently posted a link to Scott Berkun’s open letter to micromanagers, and I can’t stop thinking about it. I think that Scott’s opening lines are absolutely brilliant:

Owners of thoroughbreds never stop their horses during a race, every ten seconds, to remind the horse and jockey how to run, where the finish line is, or that it’d be a good idea to finish first. Why? It would slow them down. Only an idiot would do this.

I once worked for a micromanager who wanted me to track a dozen different milestones for every single topic that I wrote, and send her a daily report on my progress. After working for several years for managers who wanted a simple weekly “my project status is green/yellow/red.” status update, I found this new system to be highly demotivating. I felt like my new manager didn’t trust me to do my job, and the constant status updates had a definite negative impact on my productivity.

I’ve usually been lucky enough to work for managers who checked in on me every so often to ask “Is there anything I can do to help? Need anything? No? OK then, carry on.” I am a trained professional, perfectly capable of planning and executing my work by myself. I understand my manager needs to report to upper management, and as long as they let me know what they need from me, I’m happy to provide it. But I don’t come to work to write status reports, I come to write user documentation.

The other, more difficult part of this tenet is Give them the environment and support they need… The physical environment is relatively easy to provide: powerful computers, comfortable chairs, a variety of caffeine sources in the break room, etc. What is harder to quantify is the cultural environment of an office and team dynamics. Over time I’ve come to recognize that there are three types of employees that can severely negatively impact a team:

  • Incompetent employees who create problems for their coworkers
  • Lazy employees who cause more work for their coworkers
  • Toxic employees who cause morale problems for their coworkers

When I say incompetent workers, I’m not talking about people who are lacking in skills. Skills can be learned. I’m talking about people who present themselves as being experienced, senior-level employees, but they’re fooling either themselves or their employers, because they are incapable of working at the level that they claim.

I once had a project updating documentation that included examples of SQL for querying and modifying the database. I knew enough about recent database schema changes to know that the examples would no longer work, but didn’t know enough SQL to be able to correct them myself. I asked the product manager for help. Over the next several weeks he put me off, sent me the existing examples that I had told him were wrong, sent me old examples that worked against the old schema, and generally did not answer my questions. It finally became clear to me that while I didn’t know very much SQL, he knew even less. And wasn’t about to admit it. Finally his incompetence became so obvious that the company had to replace him with someone else. And I was able to get more accomplished in two weeks with the new product manager than I had been able to accomplish in several months working with the old PM.

I read a quotation that has stuck with me “Meetings move at the pace of the slowest person in the room.” I think that you can also say the same thing about teams. Incompetent employees slow down the team because their coworkers have to spent time cleaning up the problem worker’s messes and solving the problems they create rather than doing their own work.

The best example of the lazy employee can be found in the comic strip Dilbert: Wally walks around drinking coffee all day, but never seems to do any work. I suspect that we all have at least one Wally in our offices. I’ve worked with several over the years. Team members notice when someone shows up late every day, takes an hour and a half for lunch, then disappears for 45 minutes every afternoon to go pick up coffee at Dunkin Donuts. (And we also notice when managers continue to tolerate this behavior.)

If you’re a slacker, there is nowhere to hide in an Agile environment. You have to stand up every day and tell the team what work you accomplished the day before.

The third type of employee that can negatively impact a team is the toxic employee. And these are the hardest to deal with, as being toxic is less a matter of behavior and more a function of personality. A toxic employee may be a pessimist, constantly complaining about things. They may be combative, constantly arguing with people. They may spread malicious gossip. And sometimes the most brilliant people in an organization can be the most toxic, because of their arrogance.

I once worked with a writer who made enemies faster than anyone I’ve ever met before. She had usability training, and came into the company with lots of good ideas for how to improve our product, but she had no idea how to present her ideas effectively. It wasn’t so much what she said that caused her problems, but that she presented her ideas as criticisms, and often in a very insulting manner. For example, she invited herself to the UI team meeting and proceeded to give a presentation about what was wrong with their design. She wasn’t a member of that team, and hadn’t told the team leader that she would be attending, or that she wanted to provide the team with input. She just showed up, took over the meeting, and effectively told the team that they weren’t doing their jobs correctly. She was the sort of person that sends you running to the self-help section of the bookstore searching for books about how to deal with toxic coworkers. (I found strategies that saved my sanity in the book The Sociopath Next Door by Martha Stout.)

I know this is a deeply heretical statement (especially when so many people are out of work through no fault of their own), but some people need to be fired. It is the only thing that will make any change in their behavior. Poor workers need to be taught that their behavior is not acceptable. Managers need to coach problem employees. Give them a short probationary period to correct the problem, but if there isn’t drastic improvement, fire them. Some people cannot hear the message that they need to change until it costs them their job.

Sometimes firing someone is the best thing for both the team and the problem employee. The bad team member will get the wakeup call that they must make changes in order to remain employable. And the team will be more productive without the problem employee dragging them down.

Build teams of motivated individuals. Then give them the environment and support they need, and trust them to get the job done.

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 22, 2009

    Agile Tenet #3 – Deliver Frequently

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

    Number three Third 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.


    Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale.

    When I was working in a Waterfall development environment my writing process was long and drawn out, similar to writing a novel. I once worked a solid 18 months on a single release. The User’s Guide was almost completely revised, and weighed in at 450 pages by the time I was done. For that particular release I did nothing for three solid months but read through the hundreds of pages of specifications for the release, taking notes along the way of new applications being added to our application suite and new features. Then I struggled with my outline for several weeks, trying to figure out a structure that would accommodate the new material. I was writing notes and draft topics the whole time, but the new release had so many different applications, that it was hard to find a structure that would fit the wide range of new features. Once I settled on a structure, I spent almost a year playing with the software builds, exploring the new features, interviewing a dozen different product managers, writing and revising before the software and doc was actually released.

    In Write to Learn Donald Murray describes techniques used by all writers (Collect, Focus, Order, Draft, and Clarify), and urges his students to adapt them to their needs. And that list describes my writing process pretty well. My technical writing textbook, How to Communicate Technical Information, breaks the writing process down to just Planning, Writing, and Revising. However you define your writing process, in an Agile environment it is severely compressed.

    I’ve heard TWs estimate that they only spend between 25% to 40% of their time actually writing, with the rest of their time taken up with e-mail, meetings, planning, research, and other non-writing tasks. When you’re writing documentation in an Agile environment, your process is no longer the long slow march towards a major release. In an Agile environment, you’ve got to be much more efficient. You have much less time to think about what you’re going to write, because if you are going to deliver content by the end of the Sprint, you need to stay focused on tasks that support the writing.

    I’ve already written about how I use modular writing, and some of the techniques I use for being ready to publish at all times. Making the switch from the long cycles of Waterfall to shorter Agile Sprints has not been as big a shift for me as it might be for writers who were not used to delivering information in small chunks. But even so, I’ve had to learn to let go of my own expectations for the documentation. There has always been a gap between the documentation that I want to deliver and the documentation that I can deliver in a given timeframe. With a shorter timeframe, that gap widens considerably. (Thank goodness tenet #9 is Attention to Excellence!)

    It seems to me that one of the tricks of being an Agile technical writer is to be less like the novelist and more like a journalist on deadline, trying to scoop the competition with a big story. Journalists are continuously writing because they have to deliver content, be it a daily newspaper, news weekly, or monthly magazine. But unlike a journalist, the Agile TW can always go back and revise what they’ve written in a later iteration.

    Deliver documentation frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale and delivery of smaller chunks of information.

    « Previous PageNext Page »

    Create a free website or blog at WordPress.com.