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

December 3, 2009

Techniques for Being Ready-to-Publish at Any Time

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

Sprinter at the starting line

One of the things that concerned me when I was approaching a new job and a switch to Agile development was the tenant “Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale.”  I’ve spent most of my writing career at a large company that had major releases every 12 – 18 months and patch updates once a quarter.  Many of the writers in my group had one or two deliverable deadlines a year.  Since I wrote the User’s Guide I usually had quarterly updates.  Now I was facing the possibility of needing to be prepared to release the documentation as often as once a month. And as a sole writer.

My documentation set is written using FrameMaker. I’ve been using FrameMaker since release 5.5, and have gotten pretty good at bending it to my will.  I also use frequently use Microsoft Word and Excel to create and manage my projects.

Challenge – Produce Documentation for Two Separate but Similar Products
My company has two very similar products that have different markets.  There is a significant amount of overlap between the two products, but they have different names and release numbering.  As an Agile writer, I don’t have time to update a separate doc set for each product.
Solution – Single Sourcing using Variables and Conditional Text
FrameMaker lets you create user defined variables. I have created several different variables, including:

  • Full product name, for example, WidgetMaster Enterprise Suite
  • Short version of product name, for example, WidgetMaster
  • Release number, for example, Release 4.2.1
  • Directory, for when the product name appears in all lowercase, for example in pathnames, C:\Program Files \mycompany\widgetmaster\settings

I also use FrameMaker’s conditional text feature to keep track of content that is specific to one product or the other.  Text for Product A is color coded in green, and text for product B is color coded in corporate blue.  I have to be careful when applying conditions to spacing and paragraph tags, but once you learn the tricks, it’s quite easy to get your documents to look the way you want them to.  I also have separate book files, as Product A has a chapter and a couple of appendices that do not apply to Product B.

Challenge – Writing New Topics
My writing process can be a bit messy, often resulting in content that I’m not yet ready to show to others.  A new topic might start with a heading and the copied contents of an issue, e-mail, or spec. As I work my way through a new feature in the UI I might take notes or rough screen shots to document my progress.  It may be a while before there are any complete sentences in my draft. 
Solution – SCRAP paper and Draft condition
I’ve adapted old fashioned writing techniques to the digital age.  If you look on my hard drive you will find assorted files with names like Widget_NOTES.doc, SCRAP.fm and Issues_DRAFT.fm.  I capitalize the file names to make it easier to find the files that I’m working in, since I usually keep them in the same folders as my projects.  I use these files to store my raw notes.

Once I’ve started to write something that looks like sentences, I’ll copy the content into my FrameMaker book and mark it as conditional text.  I have two conditions for this:

  • Draft for content that is close to releasable, but hasn’t been reviewed and approved yet.  If I have to generate a PDF before a new topic is reviewed, I can hide the Draft condition.  Once new topics have been reviewed, I remove the condition from them.
  • Rough Draft for new content that may not be ready to publish until a later release, but that I want in the book file now.  I try to always be prepared in case I am hit by a bus/lottery (My former manager was a tender soul who didn’t like the idea of her employees being hit by a bus. She preferred to think that we’d leave suddenly because we won the lottery.).

Challenge – Managing Minor Revisions
There are always minor tweaks to be made to any documentation.  When I first started as a writer I adopted the practice of writing notes to myself in the text as I had ideas for improvements, or found things that I needed to follow up on later. I needed a way to identify that text was a note or comment, so I always put the text inside double angle brackets, like this <<Note to self – GUI is going to change, replace screen shot.>>    I also wrote notes to my reviewers using this format, <<Is the password case sensitive?>>  At the end of a release I could do a quick search and delete any leftover notes.  But in an Agile environment I was sure to have notes that weren’t ready to be deleted yet.
Solution – Comment Condition
Once again, I’m using FrameMaker’s conditional text feature.  I have a Comment condition that is bright pink.  I still use the double angle brackets, since I turn off condition markers when I send content out for review.

Challenge – Making Major Revisions
As I mentioned in my previous post, some of my legacy documentation needs some Tender Loving Care.  I had to solve the problem of how to perform some major revisions, while still being ready to publish at a moment’s notice?
Solution – Revise in Stages
Watching the developers break down a user story into small chunks has reminded me that any task can be broken down into smaller tasks.  Making a major revision can be broken down too.  Even when I’m completely tearing a book apart and reassembling it, I can work on one chapter at a time.

I start with my outline.  Since outlines are “scrap” documents, I create my outlines in Word.  I can also use the Word “document map” feature to view and navigate my draft outline as I work on it. 

Once I feel like my outline has stabilized I’ll create a new FrameMaker file and import the new outline.  If you look on my hard drive there will often be old and new files right next to each other, for example a Ch1_intro.fm file and a Ch1_intro_NEW.fm file.  Then I copy and paste the existing topics into the new outline. 

Once the copy/paste stage is complete I can abandon the old file, rename the NEW file so that I can generate the book, and use my Draft and Rough Draft conditions to manage the work as I make changes to individual topics.

Combining all of these techniques has allowed me to make some pretty significant improvements to our doc set over the past year.  Since I’ve only been working two days a week since July, I never would have been able to accomplish so much if I hadn’t found a way to manage and hide revisions while I worked.


Post Script – Our VP of Engineering stopped by yesterday to give me the good news that he’d gotten approval for me to start working three days a week instead of two.  Just what I wanted for Christmas, more income!  I hadn’t planned on posting daily for much longer, but it looks like I’ll be downshifting to every other day a little sooner than I thought.

December 2, 2009

Preparing for Agile – Modular Writing

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

Legos If an Agile Sprint is designed to complete releasable code within a 2 – 4 week time frame that means that as a technical writer I should be aiming to have releasable documentation within the same time frame.  The question is how to accomplish that goal?

Whether I would be releasing manuals or online help, it seemed to me that the answer lay in producing modular writing.  My technical writing instructor had taught us to write short topics, preferably of a page in length or less.  This was presented as a usability feature, so that when viewing online help users wouldn’t have to scroll, and when viewing printed manuals, they wouldn’t have to flip the page to complete a task.  I’ve since learned that this style of writing stand alone chunks is referred to as “modular writing.”  I like to think of it as having lots of little Lego®  blocks that I can assemble into whatever form of documentation is required.

Ever since I worked for a company that had been investigating converting their documentation to DITA I’ve been chunking my content into Concept, Task, and Reference topics.  Even if that distinction is made only inside my own head.

I consider Concept topics to be my product overviews, application overviews, business or industry specific concepts, product specific concepts, and other overview material.

When I write procedures, they are always task oriented, and thus Task topics.

I write Reference topics when I’m documenting the UI, (for example listing all the icons in a toolbar) or writing lists of reference material, for example, statuses, commands, or configuration settings.

Now comes the fun part.  *I* write modular content.  But the legacy documentation I had inherited when I started this job was not quite as modular as I would like.  The company had originally had a very competent technical writer, but after she left the company there had been a variety of people contributing to the documentation effort, and as a result the doc set needs quite a bit of Tender Loving Care.  There were two or three separate procedures lumped under a single heading (“Creating and Deleting Widgets”). There were tasks that were buried in paragraphs of text instead of being presented as numbered steps.  There was concept information nestled within the steps of procedures.  And there were topics that stretched on for pages.  How was I going to address these problems in an Agile environment?

I found my solution when I was exposed to the concept of code refactoring in our SCRUM meetings.  According to Wikipeida, “Code refactoring is the process of changing a computer program’s internal structure without modifying its external functional behavior or existing functionality, in order to improve internal quality attributes of the software.”

I’ve adapted the idea of Code Refactoring to my process of ongoing document revision and improvement.  If the developers refactor only when they are touching a particular part of the code, I have decided that I will refactor only when I’m touching a particular part of the doc.  Our documentation is manuals, so when I open a particular chapter to fix a documentation bug or add new content I work on cleaning up the rest of the chapter while I’m in there.  So, for example, when they add a new report to the product, I might do the following to the Reports chapter of the User Guide:

  • Tear apart and revise any topics that need to be re-chunked into Concept/Task/Reference
  • Ensure that each task has a separate heading
  • Rewrite any headings that are not descriptive or task based (the dreaded “Overview” topic and “Settings” topics are ripe for revised headings)
  • Reorganize the topics into a more logical flow
  • Remove any topics that are no longer relevant (reports that are no longer shipped)
  • Add new topics as required (new reports, missing content)
  • Update screen shots if necessary

The hardest part of this process has been wrestling with my own expectations for document quality.  It is painful for me to ship documentation that doesn’t live up to my own high standards.  I want to fix everything NOW.  But I don’t have the time to do that, especially now that I’m only working two days a week.

I’ve had to trust that eventually I will have the opportunity to refactor every part of our documentation set.  As long as there is continual gradual improvement (kaizen) I can feel like I’m doing my job.


Modular Writing Resources
Single Sourcing: Building Modular Documentation By Kurt Ament

November 30, 2009

Making the Mental Leap to Agile

Filed under: Uncategorized — heratech @ 7:26 pm
Tags: ,

Goldfish jumping out of his bowlI figured out a long time ago that I like structure and order. Being organized (some might say anal retentive) is one of the qualities that makes me a good technical writer. But it also means that I’m way out of my comfort zone as I’m adapting to the changes that Agile has brought to my workplace.

However, every now and then something happens that makes me think maybe I’m actually adjusting better than I think. During the Sprint Retrospective for our first Sprint, I was surprised to find myself talking someone else *out* of writing documentation.

We were discussing document reviews in our Sprint Retrospective, and one of the developers said that it would make it easier for him to perform reviews if he knew the document structure in advance. He wanted to create templates for all of the documentation that the team might possibly create. He ran over to the white board and started making a list of all the different types of documents that we could possibly think of writing, requirement documents, design documents, functional specs, and on and on. His list contained probably 15 – 20 different document types.

As I stared at his list, I found myself saying, “That’s not very Agile.”

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.

November 24, 2009

A Stranger in a Strange Land

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


Despite the fact that I’ve been a technical writer since 2001 when we started our first Agile Sprint in January I found myself feeling like a Junior Writer again.  I was adding topics to our in-house Wiki when I sent my manager the following e-mail:

Could we add this [Documentation] link to the navigation sidebar on the Wiki?  I don’t have permission to edit the MediaWiki:Sidebar page. And while we’re at it, could we please alphabetize the list of navigation links?

His reply was

Doc is now on there. Alphabetical? We are engineers we don’t alphabetize info, we sort it by the checksum of the title!

Checksum?  I am a stranger in a strange land. 

Up until now I’ve generally had Product Managers as my subject matter experts.   But now I’m spending more time in the Land of Developers than I ever have before.  And if I’m going to live here, I need to be able to speak the same strange language as the developers.

Luckily my technical writing certificate program was equal parts writing and programming.  In the programming half of the course we studied machine language, assembly language, and wrote a short program in C for our portfolio.  My first technical writing job was documenting an application written in Java, so I also took a Java course, to give me a leg up in talking to our developers.

Unfortunately that seems to be about the equivalent of knowing how to say “Please” and “Thank you” and “Where is the bathroom?” when you visit a foreign country.  It gets me brownie points with the natives for attempting to speak their language, but the fact is, I’m still translating from geek into English on a daily basis. (However, every time I explain modular writing as being like object oriented programming but for writers, I can see the lightbulbs go off.)

When I was still working full time, after almost every daily stand up meeting I found myself running to Wikipedia and Google to look up new terms.  Agile software development comes with a whole new vocabulary:

  • Burn down
  • Chickens and Pigs
  • Product Backlog
  • Product Owner
  • Scrum
  • Scrum of Scrums
  • Scrum master
  • Sprints
  • Velocity
  • User Stories
  • Xtreme programming (XP)

And then there are terms that developers use that technical writers don’t:

  • Binaries
  • Checksum
  • Kernel panic
  • Refactoring
  • Unit Testing

My Wikipedia reading sometimes led to the discovery of other, more colorful terms that I didn’t hear at the office, such as code smell or yak shaving (which I believe is similar to activities that my evil twin Skippy refers to as “Hoovering the cat”).

Understanding what developers are talking about is really your passport to Developer Country. A couple of good sites if you’re trying to get up to speed on Agile terminology:


FYI – My manager was just joking about sorting on checksum.

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.

Blog at WordPress.com.