HeraTech

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.

Advertisements

3 Comments »

  1. No, you are not.

    I’ve worked on a successful agile team that included a tech writer, analysts, QA, a UI guy and both local/offshore dev.

    Here’s the mindset, I’ll leave it to you how to figure out how to do it.

    The product (software) should be shippable (installable and usable by the customer) at the end of every sprint. What documentation would need to be delivered with that increment to make it successful? That is what you need to author during the sprint.

    Our tech writer had install, help, and configuration docs. With each team story, the analysts wrote acceptance tests, the devs coded, and the tech writer updated all her docs to align with the new functionality. She did not have a separate documentation story on the plan.

    If your team isn’t able to ship each sprint/iteration… it’s possible they are doing agile either. 😉

    Comment by Kevin E. Schlabach — November 23, 2009 @ 10:52 am | Reply

  2. We’ve been doing modified agile since 2000. Until last year I was the lone writer. My target is to have docs finished and reviewed three days after the story is done.

    Generally I draft docs based on design discussions (we don’t pre-document the design) and acceptance test docs. When the code gets useable, I walk through and refine the docs related to that story. Each story includes a task card for documentation – the story isn’t truly complete until the docs have been reviewed and accepted.

    When developers are working on behind the scenes code which doesn’t affect the user experience, I refactor the help, research documentation issues, sit in with services to listen to users, or do dreary cross checks.

    My documentation is 1800 help topics and 300 pages of tech docs.

    Comment by CMPete — December 4, 2009 @ 8:39 am | Reply

  3. […] Examining My Writing Process […]

    Pingback by Agile Doc Reviews – The Documentation Sprint « HeraTech — December 5, 2009 @ 8:53 am | Reply


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Create a free website or blog at WordPress.com.

%d bloggers like this: