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.

February 9, 2010

Collaboration – Writing is a Team Sport

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

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

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

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

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

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

And if you don’t, why not?

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

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

January 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.

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

    November 29, 2009

    Making the Transition to Agile

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

    Ready Set Go When I first started thinking about making the transition to Agile, I decided that rather than focus on how different Agile was from my current workflow, that it might be less anxiety producing to focus on what I was already doing that seemed Agile.

    I’d always been part of a cross-functional team that included (depending on the company) product managers, developers, QA testers, technical writers, support personnel, and training course developers. Although I was used to the teams meeting once a week for an hour, with Agile that would change to meeting daily for 15 minutes.

    I already had experience working with skimpy product specifications. There is a great deal of variety in the quality of design and functional specifications that product managers write. I’ve never worked anywhere with what I thought were “extensive” specs, so this idea that a company could spent all their time defining requirements and never get around to writing code was alien to me. It seemed to me that one of the appeals of Agile for developers is that they’d get to write code instead of documentation.

    I’d always written the documentation against the product, working through the UI in a development sandbox, not against the specs. So while I was worried about how I was going to estimate without specs, I wasn’t too worried about how I’d do the actual writing.

    I liked the idea of a product backlog. Due to time constraints, there was always something that was getting cut at the last minute so that I could hit my deadlines. So I was already keeping a documentation backlog of topics to write or revise for the next release.

    The whole concept of “done is done” seemed to require that the writing be broken down into small chunks. I was trained to do modular writing, breaking things down into topics of a page or less. And for the past couple of years I’ve adopted a watered down form of DITA, organizing my content into into Concept, Task, and Reference topics.

    But when I started as an Agile writer, I had more questions than answers. And after a couple of months, I still have more questions than answers about how to be the most Agile writer that I can be.

    Create a free website or blog at WordPress.com.