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.

Create a free website or blog at WordPress.com.