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

Agile Doc Reviews – The Documentation Sprint

Review discussion When I was working in a Waterfall development environment, the main documentation effort came at the end of the release cycle.  Sometimes the writers didn’t even start to receive team meeting invitations until the coding effort was well underway.  And by the time I needed documentation reviews, the product managers were often busy working on the next release.  On more than one occasion I had a PM give me a review comment about how a feature worked, and I had to show them that I was writing against the current code, while they were thinking about their design for the next release.

In an Agile environment, reviews for new features should be happening within the same Sprint as the development and testing.  But from what I’ve heard, that’s not always how it ends up working in practice.  There are Agile shops where the documentation happens a Sprint behind the development.  Which is still much quicker than in a Waterfall shop.

But what about major reviews?  Sprint reviews only cover the features being developed during a single Sprint.  At some point, the entire document or Help system needs to be reviewed for accuracy. For example, we’ve recently rewritten our installers.  So the entire Installation Guide has been rewritten and needs to be reviewed as a whole.  But we’ll also need to check the User Guide to make sure that we’re not referencing path names or files that no longer exist.

At some point in the cycle we need to plan time to concentrate on documentation reviews. I found my answer to the question of how to make this work before I had even really started as an Agile Technical Writer.  Last October, during my second week at my new job, I attended the DocTrain East conference in Boston.  [Unfortunately the company that put on the conference is a victim of the recent economic downturn and has closed their doors.]  One of the keynote speakers was Adam Hyde speaking on the topic “Read, Write, Remix: The FLOSS Manuals Story.”  This is what I wrote in my diary about his talk:

The other interesting idea that I got from his talk was that of a “documentation sprint.” Sometimes they gather 4 or 5 writers in one place (usually a nice hotel) and they’ll spend four days cranking out a manual. Since “sprint” is another Agile term, I wonder if I can talk the development team into doing one or two documentation sprints a year to help me crank out even more doc?

I took the idea right back to the office where I shared it with our VP of Engineering. The company had promised customers a new guide.  I’d been there less than a month and was still drinking from the fire hose, but hadn’t yet reached the point where the product made sense yet.  I wasn’t going to be able to deliver by the deadline by myself.  My VP loved the idea of a documentation sprint. In fact, within less than 24 hours of me mentioning the idea, he’s scheduled a meeting, we’d hashed out a general plan, and picked which week we were going to kick this off.  

During our planning discussion we’d joked about locking everyone in a conference room, ordering pizza and not letting them leave.  I said I’d dig out my official Hall Pass from my teaching days.  We ended up getting IT to set up computers in one of the conference rooms, and several of us sat and worked together during the week-long documentation Sprint. I mostly organized, formatted, and edited, which is not now I prefer to work. But since I hadn’t had time to learn the product,  I had to content myself with role-playing (rather convincingly, if I say so myself) a novice user who didn’t know anything about the product.

Our first doc sprint was a rousing success.  We went from blank page to released manual much quicker than I would have ever imagined possible.  One of the reasons why I think it was so successful was because management really got behind the idea.  Management made it clear to the developers that for a week, they were to concentrate on the doc.  And documentation reviews always succeed or fail based on management support.  If your managers don’t make it clear that reviewing the documentation is important, then reviewers don’t make it a priority.

As I like to remind people, we ship two things to the customers: software and documentation. Code needs to be tested, and documentation needs to be reviewed.

I anticipate that our next documentation sprint will be shortly before our next major release.  Scrum has enabled our developers to make some major changes to the product, and I’ve been making some major changes to the documentation set.  I want to make sure that the docs represent the current state of the product.

The FLOSS Manuals site has a book all about book sprints.

Anne Gentle blogs about doc sprints and other Agile techniques.

Create a free website or blog at WordPress.com.