Spend 80% of your time on One Thing.

As a manager of a small tech writing team in an agile environment (are there any large tech writing teams left out there?), it’s easy to lose myself in how-the-heck-can-we-keep-up-with-myriad-coders-frantically-coding thinking.

So when my manager scheduled a meeting to ask what innovations my team has planned for the next release or two, I thought of a few choice responses, such as “Um… how about documenting the new features in time for release? Is that innovative enough for ya?” and “Innovate THIS.”

Eventually I calmed down, since he’s the boss, and I have a mortgage.

I looked at the presentation I’d given after our last research period, that oh-so-short breathing time between releases. I reviewed the precious feedback we’ve gotten from a few customers and thought hard about it. I felt a bit better when I realized several of the goals we’d set for ourselves were already underway.

I dutifully wrote up a wiki page (because I can’t think without writing) that summarized a bunch of initiatives under each of our themes: process, community, quality, coverage, usability, and media. And I decided whether they’d fit into this release or the next. And I sent it off to my manager before our meeting.

He said OK, but where does all this get us?

He called my list depressing. Death by a thousand cuts.

He told me that to be successful, you need to put 80% of your time or money into one thing.

He suggested creating completely different help for just one tool. Throw out the old stuff and start over.

Once I played devil’s advocate for awhile, I began to see where he was going with this. I suggested a tool that I thought would be a good candidate. So I think we’ve picked our One Thing for this release.

Here’s how I’m thinking about our One Thing so far:

• Make sure everything the user needs to know is accessible from one place.
• Target two very different points of interacting with the help: the getting started phase and the troubleshooting phase.
• Use media that are best suited to the user and the information that needs to be conveyed.
• Make the help interesting, fun and effective. Grab and keep the user’s attention long enough to convey what needs to be understood. Defuse frustration.

And again (annoyingly), my manager is right; it’s much less daunting to try to make one thing better than to try to make everything better.

Now to persuade a few of the developers to star in our walk-through video….

The not-so-agile technical writer

I’m a technical writer who’s a big picture kind of person and that means agile development is sheer torture for me.

Going into my second agile project, I thought I would be able to go with the “flow” a bit more. I was wrong.

But, it’s important to point out that our documentation team hit all of our deadlines for new features, while substantially rewriting our help set and moving it to a wiki. I’m pleased with the outcome, but the trip was not pleasant.

This will be my first post in a series about technical writing in an agile environment. Today’s post outlines the obstacles that I face—aspects of being me (mostly). The next post will outline my coping mechanisms, as well as our team’s plan for our next project.

If there’s no follow-up post, that means that my unbridled honesty has gotten my keester kicked to the curb.

Waterfall nostalgia

I got started on this tech writing gig as a consultant. The product would be a month or two away from release, but mostly fleshed out and I’d swan in, grab the requirements documentation and the design specifications (sometimes I’d write those), play around with the tool and voilà: a manual. I could be very single minded about what I was writing and just get it done.

To be clear, I’m in no way saying that the waterfall method delivered better products or documentation, just that I had a better view of where we were going.

With agile, I feel like I’m jumping hither and yon doing all these minute tasks, with very little view of how they’re supposed to fit together. I’d often snarl to my manager after meetings that “I’m given a doorknob, a shingle and a shrub and told to go build a house with them.”

In fact, in his blog post about minimalist documentation and agile, Shannon Greywalker hits on my problem very accurately, and it’s this: “user stories are typically too granular” for minimalist documentation. Minimalist documentation, as he says, requires the “35,000 foot view”.

And what I want runs counter to the whole agile methodology: THE BIG PICTURE RIGHT NOW.

Multi-tasking versus uni-tasking

Another problem I face is that I’m a uni-tasker; I like to finish what I start—not doable when features span several development iterations and are in major flux.

There are blogs out there about what Generation Y is like, good or bad, but the one thing I do envy is their multi-tasking ability. These folks grew up doing homework, while downloading music and instant messaging their friends.

That’s the kind of splintered attention I envy. So, I got David Allen’s book, Getting Things Done, but I couldn’t finish it. I read the line about having “a mind like water” and then froze. Uh-oh. Mind like ice. When I think of my work and personal to-do lists, I’m paralyzed.

So, I signed up for meditation classes and I’m now making another attempt to read Getting Things Done. I’m hoping it’ll help me switch directions faster. Not easy when you feel like the Titanic and need an hour’s notice to hang left. Now that I think about it, the Titanic is a career-limiting metaphor.

Procrastination

Now it’s time for confession. Our documentation department fought for and won a two-week offset for our last two projects. Yep, that’s right, we trailed development by a two-week iteration.  It’s amazing that we haven’t been rounded up and thrown in agile jail.

By procrastinating this way, we hoped that features would be more fleshed out before we started writing about them. It was our vain hope that this would contain some of the rewriting efforts. We still did a lot of rewriting, but this round we were rewriting a lot of material for the wiki anyway, so the offset didn’t matter that much.

By now, you’re probably thinking that it must be very hard being me. Don’t cry for me, Costa Rica; I have ways of getting by. Tune in whenever the next post surfaces to find out how I cope and how I hope to improve.

A recent article brings up some interesting discussion.   I definitely agree that high quality code can be created without tools or any automation.

But in organizations where you have tight deadlines, fewer developers and more features than ever, something has to give.  To me, saying that you don’t need tools or automation is like saying you want to dig a hole for your pool with a spoon OR climb Mount Everest jumping on one foot OR you get the point…Sure you can write high quality code, but how productive will you be when you have your customers on your ass for the next feature?

Additional comments by the author goes on to say:
The very point of a tool is to change a process. Usually the goal is replacing a manual process, with an automated process.

Well, how is this changing your process?  Isn’t that taking something that may take 1 hour manually down to 1 minute something that is desirable?

Either way there are plenty of tools that don’t change your process.  The ones I’m very familiar with is static analysis tools.  The whole point of them is to extend and embrace your existing process.

But with that said, let’s look at how some IDEs have evolved.  Going from a text editor to an IDE, I guess is changing your process.  But what are the reasons for this?  A more targeted debugger, auto completion, refactoring etc.  What does that do? It makes you code faster and smarter.  I think I’m more than happy to change the process for that.

I sat in on an iteration review this week and came away feeling great about the team, the process and the strategic direction we taking our products.  Reflecting on the meeting I asked myself what was the magic in the meeting? The strategic direction of the product had been hashed out months ago in a grueling multi day session,  almost all of the members of the development team that were present for the review have been with the company since it’s inception back in 2001  and the meeting covered what it was billed to cover –  there was no “ oh by the way we got this new cool feature into this iteration.”

The magic of the meeting was in what I will call  “The Unspoken Agile Advantage.”  We are working towards our next major product release with 2 week iterations.  We are coming up on the end of an iteration and the team got together to review a demo of a very significant new feature. I sat in unannounced to see our progress first hand.  The demo was solid and it was one of those good news – no surprise meetings.

So what is this magic I keep referring to?  The chemistry of the team’s interaction.  In short order, major new functionality was designed and brought to life.  The team could see the results with very fast turnaround –  2 weeks, while it was still fresh in their minds.  The Agile process lends itself perfectly to “very cool, hey can we do this now” or what about changing that adjacent part of the screen to better expose these capabilities….and on and on.”  The magic was in the rapid review, the visual context of the new functionality in relation to the rest of the product and the dynamic interaction of cause and effect of the new capabilities – all centered around making the overall user experience even better than “the plans on paper.”

I am sure every Agile Evangelist would look at me and say duh…yeah that is what Agile is all about.  As a CEO it is one thing to hear we are on track with the new release and be shown multi-colored spreadsheet or dashboards,  but it is worth its weight in gold to actually see the progress maturing and the ensuing feeding frenzy of ideas amongst the development management and team members in quick iteration bursts.

I deal with many organizations that deploy the Klocwork software to the desktop so that developers can use our tools to help them find and fix bugs in their code.  The message is simple, fix your bugs before you check in your code.  Many of the organizations I deal with have a mismatch of environments and tools.  In the world of writing code it is not uncommon to find developers using Emacs, Vim, Visual Studio, Eclipse or any number of IDEs/text editors.  Nothing wrong with this, although it doesn’t offer a clean, repeatable environment but it does work.

Recently I keep running into situations where productivity seems to be thrown out the door.  Not only were the developers a mix of many (and I mean many) development environments but they made the decision to code on a platform that they do not compile on. They would write code in Windows or Linux then store their code in a central repository or some sort (in one case it was just NFS), then ssh to a different Linux machine and run the compiler on the code.  If the code fails to compile, look at that syntax error and go back to your other machine to navigate to the line of code and figure out the error.  Rinse and repeat.  Wow…