February 24, 2010

Agile Tenet #12 – Reflect on Improvement

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

Number twelveTwelfth 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.


At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly.

At my first technical writing job, at the end of every release cycle, we held a post-mortem. Each department would discuss what worked and what didn’t in the last release cycle, and management would meet and discuss what we reported. But during the next release cycle it seemed like we’d do the exact same things, follow the same process, and compile a very familiar list during the release port-mortem meeting. It seemed like no matter how many times we listed things we’d like to see change, we always maintained the status quo.

Some find it easier to list their complaints than to work towards making changes. I suspect that many of my coworkers were too set in their ways and too comfortable with the way things worked to make any major changes. And I suspect that even those who wanted to change found their old habits were just too hard to unlearn.  I know that I find that habits are hard to break, especially when I don’t have real  motivation to do so. This is why I believe that the most important part of this tenet is the second half –  “then tunes and adjusts its behavior accordingly.” The reflection is absolutely useless unless you actually act on it.

Several years ago I came across the concept of kaisen which is a Japanese word for continuous, incremental improvement. Small changes over a long time eventually add up to big changes. It is something that I’ve tried to apply to my life, because if you’re not improving, you’re either standing still or falling behind. This is one of the reasons why I belong to several different STC special interest groups (SIGs) and a couple of technical writing mailing lists. If I’m not keeping up with the industry, I’m falling behind.

Agile tenet #12 puts kaisen to work. The team regularly checks in with itself and examines their own processes. At my company we have a retrospective at the end of every Sprint. We list things that are working (and that we should keep) and things that aren’t working (that we want to change).

One of the benefits of Agile is that you can experiment with changes. A Sprint is a relatively short period of time, typically 30 days. You can try out a change, see if it works, and if it doesn’t, you can easily abandon it. For example, our team has shifted the time for our morning Scrum meetings around a bit. They’re still in the morning, but the times have shifted around between 9:00 and 10:00 a bit depending on the needs of the team (and the season, we’re in New England after all).

I keep reading articles about how important it is to risk failure in order to succeed. So often we are paralyzed with fear, afraid of doing the wrong thing, not sure what the “right” this is, so we do nothing.  But the short time span of a single Sprint lets makes it easier to risk experimentation.  You can try something new for a month, and if it doesn’t work, you can try something different.  Short term commitment is one of the benefits of Agile. And it can free up the creativity of the team, let them take risks (OK, maybe small risks, but risks nonetheless) and work on developing new team habits.

And there may also be an accidental genius to the three or four-week sprint. Convention wisdom holds that if you want to make or break a habit, you need to practice the desired behavior for three weeks. So if the team is trying to break in a new work habit, the length of a Sprint should be long enough to start building the new habit.

And at the end of the Sprint, you can reflect on your changes, decide if they’re an improvement or not, adjust accordingly, and start the cycle all over again.

January 27, 2010

Agile Tenet #11 – Self Organizing Teams

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

Number elevenEleventh 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 best architectures, requirements, and designs emerge from self-organizing teams.

Who is more familiar with the code base – management or the developers who actually wrote the code? I can hear you thinking “Duh, the developers!” Of course.

Who is more familiar with the documentation – management or the writers who spend their day researching, writing, and organizing the content? Again, the answer seems a little bit obvious, doesn’t it?

And yet how many times have we experienced managers trying to do our jobs when they haven’t got the foggiest idea what our work actually entails? I’ve worked at a variety of jobs through the years, and I have learned to appreciate a manager who has come up through the ranks. Managers who started their careers as workers understand the issues that their employees are dealing with. And the wise manager knows when to get out of the way and let their teams go to work.

As you might guess, I’m rather fond of this particular tenet. Nothing irritates me more than a manager who doesn’t trust me to do my job without their constant supervision and input. Who knows my writing process better than I do? I’ve spent years learning and honing my craft, and over the years I’ve learned what works for me and what doesn’t work.

Donald Murray wrote about the writer’s toolbox. His writing books were full of different skills and techniques that his students and readers could add to their own writing toolboxes. You might pull out one technique for a particular project, then put it away and not use it for a very long time. Some people just sit down and start writing. Others need to do research, conduct interviews, take notes, brainstorm, write outlines, conduct interviews, or any number of other techniques. Our brains all work differently, we all process information differently, and we all work differently. Thinking that one writer’s process is the exactly the same as any other is a mistake that non-writers (and even writers) can make all too often.

If one person knows best how they work, wouldn’t it also make sense that the members of a team would know best how their team functions? If you’ve hired motivated individuals (you have hired motivated individuals, haven’t you?) you should be able to step back and let the team run itself.

And it has been interesting watching this tenet in action in our Scrum teams. Rather than have a manager impose structure and order from the outside, in Agile the ScrumMaster coaches the team, but lets them provide their own structure and order. The product owner writes the user stories and assigns priorities, but the teams decide which stories they will tackle in any given Sprint. The team decides amongst themselves which developers will tackle which stories.

I know that some people are uncomfortable making their own decisions. I’ve seen it manifest in everything from students who got stressed out when asked to provide their own opinion on a test (this wasn’t in my notes!) to coworkers who couldn’t make their own decisions without polling everyone in the office about what they should do. But these aren’t the sorts of people who would thrive in an Agile environment, they are most comfortable in an office hierarchy, where management tells them what to do and how to do it.

I wonder if I’m so comfortable with this self-directed approach because I went to Montessori school as a child? Reading over the Wikipedia entry, I noticed this passage:

Applying this method involves the teacher in viewing the child as having an inner natural guidance for its own perfect self-directed development. The role of the teacher is therefore to watch over the environment to remove any obstacles that would interfere with this natural development.

Sounds a bit like a ScrumMaster, whose job it is to coach and remove impediments, doesn’t it? Montessori is about providing an environment for learning. And I think that Agile is about providing an environment where productive work can occur.

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.

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.

    Next Page »

    Blog at WordPress.com.