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

Lean Software Development – Eliminating Waste

Filed under: Uncategorized — heratech @ 1:20 pm
Tags: , , , , ,

Waste barrelI’m still digesting last week’s Nashua Scrum Club meeting. As a technical writer, one of my roles in the organization is to be a user advocate, so I’m pondering the concept that “everything not adding value to the Customer is considered waste.”

I’ve been fan of the concept of kaizen or continuous, incremental improvement, for a couple of years now. Now I can add to that muda, the Japanese term for an activity that is wasteful and doesn’t add value or is unproductive. I wish I’d been exposed to lean principles last spring when I was talking to my manager about how I wanted to handle documentation bugs.

When I was hired last October there was a pretty big backlog of documentation bugs because 1) the company had been without a technical writer for six months before I was hired and 2) the Support manager had recently had the members of the Support organization read through the entire doc set and enter bugs and enhancement requests.

Since I’m a lone writer, I would prefer that when someone finds a simple typo (misspelled word, missing punctuation) that they simply e-mail me so that I can correct it. This would lead to a very simple workflow:

1. Employee sends an e-mail to the technical writer.
2. Technical writer reads e-mail.
3. Technical writer opens document files and fixes typo.

This workflow can lead to a simple typo being fixed within a few minutes of it being found. As a fan of efficiency, this is my preferred method of dealing with typos. If someone e-mails me a problem that takes more than five minutes to fix, it makes sense to create a documentation issue to track the work on that issue (and to make sure that it doesn’t fall between the cracks and get lost in my inbox).

However, my manager wanted to track ALL documentation issues, no matter how small, in our issue tracking system. This leads to a workflow like the following:

1. Employee enters an issue. Note that not all of our employees have permissions to create issues in our system, so the employee may need to find someone else to enter the issue for them.
2. The issue has to be triaged by one or more managers, assigned a priority and a target release, and assigned to the technical writer.
3. When the writer receives the automated e-mail that the issue has been assigned to them, they may have to go to the issue tracking system to view the issue.
4. Writer opens the document file and fixes the typo.
5. Writer has to go back into the issue tracking system and change the issue status to “fixed” and then assign it to the QA manager. Because I don’t generate PDFs on a daily basis, this may not happen until days or weeks after I’ve actually fixed the typo.
6. QA manager assigns the issue to a QA tester to verify that the issue has been fixed. Sometimes this doesn’t happen until we are nearing a patch release, as the testers are testing code, not checking that typos have been corrected.
7. QA tester checks the documentation and closes the issue.

This was the workflow that we used at one of my previous jobs, where I was a member of a large doc group and the writer responsible for any particular document might change at the end of a release. But since I’m the only writer at my current job, and typos aren’t something that I need other members of the team to assist me in correcting, it doesn’t make sense to me to have so many people involved in verifying whether or not a word was spelled correctly or a period was added at the end of a sentence. Instead of a process that takes two people and five minutes, my manager wanted a process that involved at least seven people and could possibly take days or weeks to complete.

This just seems wasteful to me and not very Agile.

How do other lone writers, who don’t have peer reviewers or editors, handle editorial tasks? Especially in an Agile environment?

November 25, 2009

November Scrub Club – Scrum and Kanban

Filed under: Uncategorized — heratech @ 12:45 pm
Tags: , , ,

Bulletin board with post it notesLast Thursday night’s Nashua Scrum Club introduced me to yet another new software development term.  Kanban.  The speaker was Damon Poole, who spoke on the topic “Scrum and Kanban, Chocolate and Peanut Butter?”

Since I’d never heard the term Kanban before, I hit Wikipedia before the meeting to look it up.  But only ended up confused about how a manufacturing process applied to software development? 

After the meeting, it seems that the answer is not so much kanban, but “lean software development.”

I only took a few notes, mostly listening and trying to understand what was, for me, a new concept.  Damon started out giving a brief overview of Agile (which was useful for the majority of the audience, who were not working in an Agile environment).  Then he talked a little bit about Lean.  My notes say “providing value” and “continuous improvement”.  Aha,  I know that one, kaizen!   He mentioned 14 critical mass Agile practices, but I was only able to scribble down five before he flipped to the next slide.  I do hope that the slide deck is posted online at some point.

The next part of his talk focused on process.  He had some color coded slides that showed several iterations, with Development doing their work during one iteration, and QA doing the testing during the next iteration.  My notes say “This is not Agile.”

He talked a bit about how to break down large stories into smaller ones by listing the tasks, and then determining the critical tasks and the dependencies between them.  He had some great slides for this, which I appreciated, because I’m a visual learner.  And I was grateful that when he talked about workflow that he included Documentation (Specify > Design > Code > Unit Test > Integration/Doc > Testing) because so many people seem to forget or ignore Doc when talking about Agile.

Then there were color coded slides, showing several small stories being worked on during several different sprints and showing how there were bits of downtime for the testers while they waited for the code.  Then he had a rather spiffy animation that removed the lines indicating the iterations, and sliding the testing tasks right up to match the coding tasks.  “Getting rid of the iteration fills the gaps between coding and testing.”

He talked about decoupling the tasks of Agile from the iteration/Sprint.  Backlog grooming can happen anytime.  Story point estimating can happen anytime.  These tasks can be decoupled from the Retrospective or the Planning phase of a Sprint.  “Done” is decoupled.  Done is no longer the end of the iteration, but the end of the story.  And when you’re finished with a story, you pull the next story off the top of the backlog and start working on that.  He also talked about a Work In Progress (WIP) limit, that no more than X story points could be in progress at any one time.  During the Q & A someone asked when you demo?  His answer was not every time you finish a story (which might be every day or two) but when it makes sense to the team.

Damon finished his talk with a list of Lean and Kanban concepts that he thinks can be applied to Agile:

  • Decoupling
  • Lean thinking
  • One piece flow
  • Work in Progress limits
  • Eliminating waste


Related Blog posts that I found while researching Kanban:

Defining Kanban

Between kanban and pair programming lies the feature brigade

Related Books:

Do It Yourself Agile by Damon Poole – Free download!

Lean Software Development by Mary and Tom Poppendieck

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

November STC Meeting – Documentation in an Agile Environment

Filed under: Uncategorized — heratech @ 3:17 pm
Tags: , ,

Last Wednesday night I attended the monthly Boston STC meeting.  The topic was “Documentation in an Agile Environment.”  The discussion panel consisted of two writers, a doc manager, and a QA tester.  At the beginning of the evening the moderator polled the audience and the vast majority of the audience was not working in an Agile environment. From the questions they were asking, it seemed that many of them were completely new to the concept of Agile programming.

During the question and answer period at the end, one of the older members of the audience asked a question about writing process.  She said, “It seems like you start with the outline.  When do you have time to do the brainstorming?”  That struck me as an odd question.  The way she asked seemed to imply that an outline was NOT where you start.  I got the feeling that she thought the proper process for writing was to brainstorm, then write an outline, then start writing.  It made me think a lot about my own writing process and how it might be vastly different from writers of a previous generation.

I learned the craft of writing at the University of New Hampshire. My four years at Phillips Exeter Academy had given me a solid foundation as a writer, but it was at UNH where I developed an appreciation for the mechanics of writing.  And that was probably due to the influence of Donald Murray on the UNH English department.

My freshman composition class used his Write to Learn as our writing text.  And it was through this book that I was introduced to the idea of the writer’s toolbox.  A writer can have many different tools, some that they use all the time, and some that they may only pull out for particular projects.  There is no One Right Way To Write.  And that’s an important thing to remember.

One of the panelists answered her by saying that when you’re doing Agile writing, you work during the sprint to document the feature, then during the next sprint you work on the next feature. “You write it.  It’s done.  You don’t come back to it.”  Which got me to wondering, when do you have time to write conceptual information?  Almost everywhere I’ve worked, the procedures (“how to”) are adequately documented, but what is lacking is information about “why” you use the feature and the “when” or best practice information.  I’ve spent most of my writing career trying to fill these holes.  And it takes time to be able to determine what needs to be written in the overviews and develop enough customer and product knowledge to be able to write examples and best practices.

Donald Murray also wrote the Craft of Revision which also holds a spot on my bookshelf.  While I don’t write nearly the number of revisions that Murray did (he was almost a compulsive rewriter) I do often return to things that I’ve written, give them a re-read and revise my work.  I don’t often do full fledged revisions, but there are often small improvements that can be made. Especially when there is content that was written under deadline pressure where I didn’t understand a feature well enough to write a solid overview.  Or when I have learned something new about how customers are using our product and can add real-world examples. 

I don’t think I’ll be able to write something and then never come back to it.  Luckily there will be sprints when the developers are working on architecture stories or something else that happens behind the scenes and doesn’t need user documentation, and I’ll be able to go back and tweak my documentation.

One of the things I’ve been struggling with is how my writing style fits into an Agile development process.  I’ll be writing more about that in upcoming posts.


Post Script

In writing this post I learned that Donald Murray had died in 2006.  While I was never his student, I learned a great deal from his books, and read his column in the Boston Globe for many years.  It is because of Donald Murray that I think of writing as a craft, and myself as a craftsman.  I also discovered this wonderful appreciation of Donald Murray.

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.

November 20, 2009

How to Start Blogging – Just Do It

Filed under: Uncategorized — heratech @ 8:16 pm

Nike Just Do ItI keep reading articles about branding yourself online and how blogging is good for your career. I registered this blog name back in June, intending to start blogging about technical writing and Agile documentation practices.  But clearly I’ve been unable to get started, despite the fact that I’ve been unemployed, then partially employed all summer. (I’m working two days a week for the company that laid me off).

I think I’ll just have to stop worrying about what my “First Post” will be and just dive in or I’ll never get started.

Create a free website or blog at WordPress.com.