HeraTech

January 6, 2010

Agile Tenet #8 – Sustainable Pace

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

Magic 8 Ball Eighth 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.

*****

Agile processes promote sustainable development. The sponsors, developers, and users should be able to maintain a constant pace indefinitely. [emphasis mine]

Ah, a constant pace. Technical writers aren’t used to that. At least not in a Waterfall development environment. Waterfall technical writers are used to a significant amount of slack time at the beginning of the production cycle, then a stretch of regular work while coding continues, followed by a frantic scramble, often involving overtime, at the end of the production cycle.

One of the big disadvantages I can see to adopting Agile Sprints is that TWs lose the slack time at the beginning of the development cycle. I don’t know a single writer that has enough time to accomplish everything that they’re expected to do. Writers often use that beginning-of-the-cycle down time to catch up on projects that are important but not urgent, like researching writing tools, evaluating documentation processes, designing templates or style sheets, developing style guides, or just plain catching up on everything they didn’t finish in the rush to release. And heaven forbid you need to convert a large legacy documentation set to either a new tool or a new process. How on earth do Agile writers find time for big projects like adopting DITA? The short Sprint timeline makes taking time away from writing for things like conferences, training, and a well-earned vacation a little harder to plan.

Or maybe I’m still making the mental adjustment from being a member of a documentation team to being a sole writer. Even though it’s been a few years, it still feels weird to realize that I am the entire team now. And that if something needs to be done, there isn’t anyone but me make sure that happens.

One of the clear benefits I can see to adopting Agile Sprints is they eliminate that last-minute documentation rush at the end of the release cycle. Or if the scramble isn’t completely eliminated, at least the stress is spread around a bit more evenly so it doesn’t feel so bad. I can really embrace the idea of working at a steady pace.

But I keep bumping up against my fears about who gets to define what a “steady pace” is and whether or not my own personal, idiosyncratic writing style can be made to fit into the Agile mode. What about when I have writer’s block? (Yes, even technical writers get writer’s block.) There are days when the words just don’t flow. This is one of the reasons why I usually have a couple of side projects going at any time. If I can’t get my writing mojo to work, I can switch over and do some training, work on my glossary of product terminology, do some indexing, or spend time trawling the network/wiki for other useful documents that no one thought to forward to the writer. But those side projects, while productive, are not usually the sort of things that would fit neatly into a user story. Thus my anxiety about keeping up a steady pace of work.

Thinking and writing about this tenet reveals my anxiety that Agile is about forcing me to become more productive, ever increasingly more productive. I’m not a slacker by any means. At least not when I compared my production to the other writers when I worked in a doc group. And when I compare my page count from one year’s work to my estimates for what I should have been able to produce (based on the Dependency Calculator), I’m cruising right along. So why do I always feel like business is never happy with a productive employee and always wants more work (and for less pay)? And that no matter how hard I work, it will never be good enough?

Or maybe I’m just feeling uncomfortable about admitting to non-technical writers that the majority of my time is not spent writing, but on other activities? There is this misconception that all writers do is write. Judging from the number of writers blogs I read (both literary and technical writers) most writers spend less than half their time actually writing. Most non-writers don’t understand that all that non-writing contributes to the writing. And that “doing research” is not code for “farting around on the internet.” At least, not usually.

Or maybe I’m dealing with my own attempts at sustaining a constant pace of posting to this blog. And I’m finding that despite my huge list of ideas for possible posts, some weeks it is easier to generate three posts and other weeks it is a bit of a struggle. Of course, the only person requiring me to post three times a week is me. And perhaps the whole point of this post was to get me to realize that the person who has the highest expectations for my work is not my employer, but me. And that I need to give myself permission to find my own sustainable pace.

December 22, 2009

Agile Tenet #3 – Deliver Frequently

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

Number three Third in a series of posts examining the Twelve Principles of Agile Software and how each of these tenets can (or can’t) be applied or adapted to technical writing.

*****

Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale.

When I was working in a Waterfall development environment my writing process was long and drawn out, similar to writing a novel. I once worked a solid 18 months on a single release. The User’s Guide was almost completely revised, and weighed in at 450 pages by the time I was done. For that particular release I did nothing for three solid months but read through the hundreds of pages of specifications for the release, taking notes along the way of new applications being added to our application suite and new features. Then I struggled with my outline for several weeks, trying to figure out a structure that would accommodate the new material. I was writing notes and draft topics the whole time, but the new release had so many different applications, that it was hard to find a structure that would fit the wide range of new features. Once I settled on a structure, I spent almost a year playing with the software builds, exploring the new features, interviewing a dozen different product managers, writing and revising before the software and doc was actually released.

In Write to Learn Donald Murray describes techniques used by all writers (Collect, Focus, Order, Draft, and Clarify), and urges his students to adapt them to their needs. And that list describes my writing process pretty well. My technical writing textbook, How to Communicate Technical Information, breaks the writing process down to just Planning, Writing, and Revising. However you define your writing process, in an Agile environment it is severely compressed.

I’ve heard TWs estimate that they only spend between 25% to 40% of their time actually writing, with the rest of their time taken up with e-mail, meetings, planning, research, and other non-writing tasks. When you’re writing documentation in an Agile environment, your process is no longer the long slow march towards a major release. In an Agile environment, you’ve got to be much more efficient. You have much less time to think about what you’re going to write, because if you are going to deliver content by the end of the Sprint, you need to stay focused on tasks that support the writing.

I’ve already written about how I use modular writing, and some of the techniques I use for being ready to publish at all times. Making the switch from the long cycles of Waterfall to shorter Agile Sprints has not been as big a shift for me as it might be for writers who were not used to delivering information in small chunks. But even so, I’ve had to learn to let go of my own expectations for the documentation. There has always been a gap between the documentation that I want to deliver and the documentation that I can deliver in a given timeframe. With a shorter timeframe, that gap widens considerably. (Thank goodness tenet #9 is Attention to Excellence!)

It seems to me that one of the tricks of being an Agile technical writer is to be less like the novelist and more like a journalist on deadline, trying to scoop the competition with a big story. Journalists are continuously writing because they have to deliver content, be it a daily newspaper, news weekly, or monthly magazine. But unlike a journalist, the Agile TW can always go back and revise what they’ve written in a later iteration.

Deliver documentation frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale and delivery of smaller chunks of information.

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

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.