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.

    December 18, 2009

    Agile Tenet #2 – Welcome Changing Requirements

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

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


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

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

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

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

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

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

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

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

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

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

    December 16, 2009

    Agile Tenet #1 – Satisfy the Customer

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

    Business route 1 The Agile Manifesto includes Twelve Principles of Agile Software. Over the next dozen entries I’ll look at how each of these tenets can (or can’t) be applied or adapted to technical writing. And then, as a wrap up, I’ll propose my own list of Agile Principles for technical writers.


    Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.

    Companies deliver two things to customers, software and documentation that explains how best to use it. Developers deliver software. Technical writers deliver user documentation. And technical writers, like developers, aim to “satisfy the customer” when we create our deliverables.

    It’s hard to satisfy your customers if you don’t know who they are, so one of the first things good technical writers do is perform an audience analysis. What industries do your users represent? Who are the people using your product? Are they students, office workers, managers, the general public? What level of computer experience do they have? Are they novices, experienced users, system administrators? What environments are they working in? Are they outdoors, in an office, in a clean room? Sometimes this information is easy to come by, and other times we have to take our best guess.

    “Early and continuous delivery” of the most up-to-date information is a constant challenge for TWs. In the not so distant past, when TWs were mostly producing hard copy manuals, they were restricted by the lead time required for printing. Often the documentation was out-of-date by the time the product was released. Now that most of us are delivering our documentation as PDFs or online Help, we can release updated deliverables much more quickly. However, TWs may still be restricted to releasing documentation once a quarter or less. At a previous company we localized into a dozen languages, and often were not allowed to release updates if there wasn’t the budget to translate the content. The reason for this was never fully explained to me, but it was intensely frustrating to have corrections and new content and not be allowed to release them to our customers. Currently, I’m working as a lone writer for a company that doesn’t yet localize. So I can update the documentation as often as I like. Since we have a patch release cycle of 6-8 weeks, I update the docs whenever we release a patch.

    Developers deliver “valuable software”, but what makes documentation valuable? I think that Developing Quality Technical Information sums it up quite nicely, when they say that quality technical information is
    • Easy to use
    • Easy to understand
    • Easy to find

    Valuable documentation helps customers do their jobs. Customers don’t search the documentation for headings like “Using the Widget Dialog Box.” They look for “How to Order Widgets” because they don’t know which feature they need to use, but they do know the task that they need to perform. At every technical writing job that I’ve had in my career, I’ve spent my time turning feature based documentation into task based documentation. I focus on breaking the documentation down into small chunks, organizing it effectively with meaningful headings, and indexing it as thoroughly as possible. And whenever I can, I also include best practices for how to use the software and tips for how to be more efficient.

    The technical writer’s highest priority is to satisfy the customer by providing useful documentation.

    December 14, 2009

    Adopting or Adapting Agile

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

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

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

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

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

    December 11, 2009

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

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

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

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

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

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

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

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

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

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

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

    December 9, 2009

    Chickens and Pigs

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


    After The Layoff and The Return, I was only working two days a week, and stopped attending our daily Scrum meetings.  I figured that my time was better spent scrambling to catch up on the backlog of documentation work waiting for me after my six-week absence.  Now that I’ve added a third day a week, it seems like time to return to the team room and start attending our daily stand-up meetings again.  Which brings us to today’s topic, Chickens and Pigs.

    When Agile practitioners talk about the participants in the daily meetings, they refer to them as being either Chickens or Pigs, depending on their involvement in the project.  Jeff Attwood lists some alternate terms that could be used, like “players” and “spectators” but many people use the Chicken/Pig terminology, which comes from a joke in Schwaber and Beedle’s Agile Software Development with Scrum:

    Chicken: Let’s start a restaurant!
    Pig: What would we call it?
    Chicken: Ham n’ Eggs!
    Pig: No thanks. I’d be committed, but you’d only be involved!

    Your Chicken/Pig label determines whether or not you get to talk in the daily stand up meetings or are restricted to an observer role.

    • A Pig is someone who is accountable for the outcome of the project. They are the worker team members. Mike Cohn refers to these people as “having their bacon on the line.”  Developers are almost always Pigs.  Testers are almost always Pigs.
    • A Chicken is someone who has something to gain by the Pigs performing, but in the end, really do not contribute day-to-day to “work.”  They may not be part of the team, but may attend the daily stand-ups to monitor the team’s progress. Upper management are almost always Chickens.  Support and Marketing are Chickens.

    So the question we will address today is, ‘Are technical writers Chickens or Pigs?’  The answer to this question, like so many questions that get asked in the TW community, is “It depends.”

    During our first couple of Sprints my company had multiple Scrum teams.  Since we were new to Agile, my manager and I discussed whether or not I should attend all the Scrum meetings.  One team was focused on stories that didn’t affect the user documentation, so for the first Sprint I only attended one Scrum meeting. In later Sprints I was a Pig at one daily stand-up and a Chicken at another.

    The Case for Chickens

    Technical writers may belong to multiple Scrum teams at one time, and may choose not to attend all of the daily stand-up meetings.  If you’re not attending the Scrum on a daily basis, you’re probably a Chicken.

    Technical writers may be working on many simultaneous projects (especially lone writers, who may also be developing marketing and/or training materials).  Technical writers may be documenting several different products, while the Scrum team is focused on a single product or portion of a product.  If you’re just attending the Scrum to keep track of a team’s progress while you’re working on something else, you’re a Chicken.

    But Chickens are often management, and TW are seldom managers and writers.

    The Case for Pigs

    Pig roles are considered core team members, people who do the work of the Scrum.  Pigs are responsible for the Sprint deliverables.  For most team members, that means developers and testers.  I firmly believe that technical writers are Pigs.  TWs have customer deliverables.  Software companies ship two things to customers, software and user documentation in the form of manuals and online Help.  Customers need documentation to understand how to use the software. The technical writer’s deliverables are just as important as the other Pigs’ deliverables. 

    And being in a Pig role grants the TW the right to answer the three daily questions:

    1. What did I do yesterday?
    2. What do I plan to do today?
    3. What is blocking my progress?

    Number three is the Power Question for Agile technical writers.  It lets you stand up in the team room and say, for the rest of the team to hear, “I’m blocked because Dave Developer hasn’t answered my questions yet.”  Or “I’m blocked because I’m still waiting for Sam SubjectMatterExpert to review my draft.”   If Agile is about empowering workers to be more productive, then technical writers must be considered Pigs. 

    Despite the fact that I’m back in the Scrum, my current projects are not yet synched with the Sprint.  So while I’m still playing catch up, I’m just an observer, and I’ve cast myself as a Chicken.  But I’m a Chicken who is scheming how to escape the chicken yard and get back into the pig pen.

    Chicken Run

    Chicken Run © Ardman Animations

    Wikipedia explains Chickens and Pigs

    Jeff Sutherland on Contributors and excess overhead

    Jeff Atwood on Chickens, Pigs, and Really Inappropriate Terminology

    December 7, 2009

    Why I am Renewing my STC Membership

    Filed under: Uncategorized — heratech @ 8:25 am

    Society for Technical Communication logo When I sit down to pay bills tonight I will be renewing my membership to the Society for Technical Communication (STC). There were major changes in the dues structure this year, including a change to a la carte benefits that resulted in a rather hefty price increase. It’s been a couple of years since I worked for an employer that picked up my STC dues, but even though I’m currently underemployed, I’m still renewing my membership. Here are my reasons why.

    Job Bank
    When you’re looking for work you need to remember that the candidate screening process is a two-way street. Companies are weeding out candidates that are a poor fit for the job, and likewise, you should be weeding out companies that are a poor fit for you.

    If a company lists an opening on the STC job board, I can be pretty sure that they already know that a TW is not an administrative assistant. I won’t have to spend my interview explaining what a technical writer can do for them. Instead I can focus on what *I* can do for their company. I’ve had bad jobs and bad bosses before, and have reached the point in my life where no amount of money makes up for a job that I can’t stand or is so stressful that it affects my health. I’m looking for work that I will enjoy and where I can make a contribution. As Whitney Postus recently posted, “Life is too d*mn short to spend it on things that don’t twirl your beanie.”

    Job Definition
    The STC has been working with the BLS since 2007 to update its definition of the technical communications profession. “Having the US Bureau of Labor Statistics recognize technical writers as a profession distinct from all other writing professions independently confirms STC’s claim that not all writers can do technical writing,”

    This is a huge win for the STC. Previously the US Department of Labor put all writers in the same category. Technical writers were lumped in with playwrights, novelists, journalists, and poets. Yes, some writing skills are universal, but novelists don’t need to know CSS. And Playwrights don’t tend to use writing tools like AuthorIT, Flare, FrameMaker, or RoboHelp. And poets definitely don’t need to know DITA or XML. The list of additional skills that may be required by technical writing is long, and probably fodder for another post.

    Salary Survey
    When I first made the career change to technical writing, the STC Salary Survey was invaluable. Having salary data broken down by zip code was very helpful, since I live in MA, where the cost of living is higher than in other parts of the country. However the STC has changed how they collect salary data, and the jury is still out on whether or not the new survey is as useful as the old one. If I decide that it isn’t, I may have to resort to using salary.com or glassdoor.com when researching salary data.

    Local Chapters / Networking / Workshops
    I happen to live in an area that gives me access to two different STC chapters. I am within a half hour of both the Boston Chapter and the New England chapter (which tends to meet in NH), which gives me double the networking and educational opportunities. The local chapters put together workshops that often end up being very timely and helpful. I picked up tips at one workshop that made me look like a hero back at the office the very next week.

    I really enjoy having articles about technical writing delivered to my door, wrapped up in a shiny pretty package. I like to leave them lying around on my desk at the office, to read on those days when I’ve got writer’s block, but need to do something productive. Yes, I could read it on the Web, but I’m more likely to read it as hardcopy. And it’s hard to leave browser bookmarks lying around so that your coworkers see that you belong to a professional organization.

    Special Interest Groups
    I’ve been a member of the STC since 2001, and in that time I’ve been a member of a variety of different SIGs: Indexing, Instructional Design, Single Sourcing, Lone Writers. I joined the Lone Writer’s list when I was still a member of a doc group, and they are one of my more educational and entertaining mailing lists. Definitely worth the pittance that is charged for SIG membership. This year I plan to sign up for the following SIGs:
    • Consulting and Independent Contracting
    • Emerging Technologies
    • Lone Writers

    The STC Needs Support in Times of Crisis
    I’ve seen moments of crisis like this in my hobby organizations, where members want to flee what they see as a sinking ship. But leaving is not the way to change an organization. Unless the change you want to see is that the organization withers and dies. There are many talented people out there agitating for change in the STC. I want to give them time to make their changes so that the organization can continue to attract newer, younger members.

    And I need to recognize that I get out of the STC what I put into it. I tend to lurk my SIG mailing lists. I need to start posting more frequently, to give back to the SIG communities. I’ve also started attending my local chapter meetings again. I’d love to participate in the competitions, but unfortunately they happen in the fall, when my weekends are completely booked with other activities. But since I cannot participate as a judge, I will start working again towards the goal of entering my work as a participant. Years ago I submitted one of my first projects and received some very useful feedback.

    Professional Organization
    And I have my own personal reason for continuing my association with the STC. Before I was a technical writer I was a secondary school English teacher. When I started my second year of teaching I was strongly “encouraged” to join the teachers’ union. Joining was technically voluntary, but in reality, it was socially unacceptable to be a non-union member in our district. The only reason I’d avoided the peer pressure during my first year was because everyone knew I was planning a wedding, and union membership dues were expensive.

    The word “union” means blue-collar workers to me: seamstresses, hotel chambermaids, electricians, plumbers, etc. When I worked briefly for UPS in college, I was a member of the Teamsters union. While there are white-collar professions, like airline pilots, that have unions, most of the professions that require a college education are represented by a professional organization, not a union. I know it is mostly semantics, but it always irked me that teaching, a career that requires a minimum of a Bachelor’s and usually a Master’s degree, is represented by a labor union and not a professional organization.

    So I’m thrilled to finally be working in a career that has a professional organization. And even with the increase, my STC dues are cheaper than the initiation fee that I paid to join either the teachers union or the Teamsters. While I know this may not be an argument that sways anyone else, it has some very powerful symbolism for me and the way I think about my chosen career.


    Other folks who have blogged their thoughts on STC membership

    Paul Pehrson – The STC Crisis: the Take of a “Young” Writer

    David Farbey – Does the STC Deserve to Survive?

    Reprint of Monique Semp’s letter on the Lone Writer’s SIG

    Next Page »

    Create a free website or blog at WordPress.com.