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.

Blog at WordPress.com.