At the risk of sounding like a co-dependent, in this post I discuss coping mechanisms that a “big picture” technical writer (say, like my friend Beulah) can use to adjust to working in the granular conditions of an agile environment.
Don’t give up the big picture
When you work on a bunch of stories or tasks, it’s trees, trees, trees everywhere you look and not a forest to be found. This means that a nice concise how-to could be a long way off while you document myriad features.
My advice is to finish the pieces and try to get to the minimalist documentation afterwards. In fact, Shannon Greywalker suggests going back and fixing things up later, but mentions that the business case for this can be a bit weak. I think it’s worth the effort if you can swing it.
I’ve blogged before about how workflow can be helpful in getting the big picture. If the feature is big enough, workflow is your friend and can really pull you through.
Go for “What’s New” first
For each release, we document the cool new features on a “What’s New” page and “What’s New” is where I like to start.
If you can neither summarize nor explain why people would want to use a new feature, you have no business documenting it. “What’s New” keeps me focused on the whole point of the development work in the first place.
I was a slow adopter of XPlanner, which is the tool our team uses to document development, testing and now, documentation.
Documentation has a separate project in XPlanner where we track our stories. At first, I found it difficult to update XPlanner regularly because some of our work can be difficult to account for.
For example, one our sales engineers is a prodigious reader of documentation who meanders over for his (thrice) daily “found a spelling mistake” or “did we document?” or “why can’t titles be printed on the PDFs generated by the wiki?” questions. All good points, with some requiring immediate action and others requiring medium and long-term planning.
But after reading Getting Things Done, I can really see XPlanner as a great life planning tool. See the screenshot above. For low self-esteem days, I recommend first completing tasks such as “Wake up”, “Shower” and “Eat breakfast” under the Personal Maintenance story.
We’ve gone from blanket procrastination, which was a two-week offset, to carefully picking features that could benefit from a little more “fleshing out” before documentation. I like this approach because we show great planning with our procrastination.
For example, I like to spend bigger chunks of time on one thing, so I may delay documenting a bigger feature in favor of knocking some smaller stuff off the list one week, so I can string together several days in a row for the big stuff. I work better that way.
Ask a lot of questions
My modus operandi is asking as many questions as possible. Be annoying, but in a friendly and charming way. There’s an art to asking good questions, but sometimes it takes a bunch of stupid ones to get there. Dive in.