HeraTech

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.

Advertisements

December 9, 2009

Chickens and Pigs

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

ChickenPig

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

November 23, 2009

Examining My Writing Process

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

Last Wednesday’s STC meeting got me thinking about my writing style again.  While I’m always writing, it’s not a linear progression from spec to outline to topics to completed project. 

Until I started working in an Agile environment, my progress on a project went something like this:

  1. Read the design specifications and functional specifications.  Try to get an idea of what features were being built.  If I was very lucky, the specs would include a use case, describing what the customer wanted the software to do.
  2. Count up the number of new applications, tabs, subtabs, actions, dialog boxes, buttons, etc.  This is usually the point when I could start estimating doc effort, as each feature and/or task will usually result in at least one new topic, with a small fudge factor added to cover additional concept or reference topics that might be required.
  3. Generate an outline based off the projected UI features.  Each tab or subtab generally gets a concept topic.  Each action, button, or dialog box usually gets at least one task topic, and sometimes two (as in “creating a widget” and “deleting a widget”).  Estimate the number of concept tasks for toolbars, types of widgets, possible widget statuses, commands, etc.
  4. Start writing procedures.  Open this, select that, enter something, click save.  If I’ve got a well written spec I can often start on a draft before the software is even coded.  Sometimes you can write a complete draft of procedure before the software is even stable.  But it’s more likely that I’ll end up writing a partial procedure with the first several steps of a draft procedure then write myself a note that “Click X and what happens next? Software crashes as of Build# on Date ##/##/##.” 
  5. Next I generally add reference material.  Depending on the software, it might be documenting toolbar buttons, icons, commands, possible statuses, etc.
  6. The last thing that I usually write are the concept topics: overviews of new features, descriptions of new tabs, subtabs, screens, best practices.  It usually takes a while to really “grok” the software and how customers will use it.

When we first made the switch to Agile in January 2009, my manager wanted to manage me like the rest of the development team.  The developers had user stories, I had documentation stories.   The developers generated a list of tasks and then estimated story points for their stories.  I generated a list of tasks and topics and attempted to estimate my doc stories.  The developers kept a burn down chart, and I did the same. 

The only problem was, writing documentation is not like writing code and I don’t have a linear writing process.  I don’t tend to start on a topic, write it, and move on to the next topic.  I tend to work on multiple topics at once, writing as much as I can on one topic before moving on to the next.  Sometimes I’ll have an insight in the car during my commute and will need to capture that before I forget it.  I keep notebooks in my car and in my purse so I can scribble notes to myself. 

My manager expected me to work like a developer.  To pick one task and work on it until it was completed.  But I couldn’t write the doc until there was completed code.  And the first four sprints we didn’t have completed code until the last day or two of the sprint.  So if I can’t write until the last couple of days of the sprint, what am I supposed to do for the first three weeks?  (I spent my time closing doc bugs, many of which had been open since before I was hired.)

I wonder how I’m supposed to adjust my writing process to fit into Agile. I’m a multitasker.  I usually work with multiple files open at once.  My brain tends to makes connections between what I’m doing and something that I will be doing in the future, or something that I wrote in the past.  I’m a list maker.  I’m frequently opening up files and making notes of questions, resources, further research to follow up on later.  Part of this is by necessity.  Writers almost never have the luxury of only working on one project at a time.  Especially lone writers.  Right now I’m writing an Installation Guide, working on fixing doc bugs for the next patch release, writing and estimating doc stories for the past several sprints of development.  And my work is dependent on having functional code.  If I try to work through a procedure and the feature isn’t complete yet, I’ll put the procedure aside and work on something else. 

At Wednesday’s STC meeting the two writers said that they document one sprint behind their Agile development teams.  Both of the writers have been doing Agile for three years.  Before we both got laid off, my manager and I had agreed that this was the approach we were going to try.  Now that I’m only working two days a week, I don’t really have a choice but to write the doc after the developers have finished a sprint.

And yet, at the Nashua Scrum Club meeting on Thursday, someone said that if you’re doing testing or writing documentation a sprint behind development that “You’re not doing Agile.”

So, am I doing Agile documentation?  This is a question that I have yet to answer.

November 21, 2009

Approaching Agile

Filed under: Uncategorized — heratech @ 8:31 am
Tags: , , , , , , ,
Little girl peeking through fence

Sneaking up on it

I think I was destined to become an Agile technical writer.  In the summer of 2008 I was working for a small software company that produced two different products.  After finishing up a stretch of concentrating on the documentation for product A, I checked in with the product B developers in New Zealand.  I discovered that they’d decided to adopt Agile development without telling me. 

I responded the way I always do when faced with a new idea.  I did some research.

I started out by checked the Techwr-l archives for threads that mentioned Agile.  I’ve been a member of Techwr-l since 2005, and since I use G-mail to manage my list subscriptions, it was fairly easy to find the few discussions of Agile from the past couple of years.  Unfortunately, what little I found didn’t sound too encouraging from a tech writer’s point of view.

I also looked through my collection of back issues of the Intercom, the journal of the Society for Technical Communications.  I found two articles about Agile documentation:

  • Adapting to SCRUM: Challenges and Strategies (July/August 2007)
  • Extreme Documentation (February 2003)

Wikipedia and Google turned up plenty of articles, and also led me to the Agile Manifesto and Scott Ambler’s Web Site.   I had to do quite a bit of reading before I finally realized that when Agile proponents were writing things like “Documentation should be just barely good enough.” and “The benefit of having documentation must be greater than the cost of creating and maintaining it.” They were talking about project documentation (design documents, functional specs, etc), not product documentation like User Guides and Help. And with the exception of the STC articles, none of the resources I was reading were talking about what a technical writer would produce, or how they fit into Agile (other than being part of the Scrum team).

I had just started reading Agile Software Development with Scrum when a friend forwarded a job opening to me.  The job description sounded like a very good fit with my skills and interests.  The company was looking for someone with experience working in an Agile software development environment.

By this point I’d learned enough about Agile to know that the way we were implementing it at my company (developers in two different cities, the tech writer and project manager on a completely different continent) was not going to be conducive to my success as an Agile Technical Writer.   And I was intrigued by Agile. I now knew enough to be able to “talk the talk” during my interviews.  During my interview I quizzed the VP of Engineering.  They were still using the Waterfall Model, but were planning to switch to Agile development at the beginning of 2009.  

I liked the idea of getting in at the beginning and being able to shape the way the technical writer fit into the Agile team.   They made me an offer, I accepted, and I started work there in October 2008.

Fast forward to May 2009 and the end of Sprint 4.  The last day of the sprint our company had a layoff, and I was one of the casualties.  Six weeks later they called me back to work part time (two days a week).  So while I’m still working in an Agile environment, I’m no longer embedded with the team working to document the current sprint.  Hopefully that will change as the economy starts to recover.

Create a free website or blog at WordPress.com.