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….

Our new documentation wiki is up and running!

For awhile it seemed like we’d never do it. We have a team white board that records our panic level, and for several weeks, the level was up around “hysterical” and “wanting to open my own daycare”.

We also have a white board in front of the doc area, in a hallway where everyone walks by to get to the kitchen.  At one point when we were particularly frustrated with MediaWiki, the topic was “names for the new doc wiki”. A few good suggestions:

the gaping maw, or "the wiki is never done"

And the best one, though we decided it would be unprofessional to make it official:

RTFW

Fortunately, when I was ready to throw in the towel, our IT guy stepped into the ring and beat MediaWiki into submission. He installed extension after extension, found a search engine that worked for us, and configured a great PDF creator. He moved the entire Wiki a few times to improve performance and security. And he was much more tolerant of the state of MediaWiki’s documentation than I was.

So, if you’re a small documentation team thinking of moving to a Wiki, what do you need to make it work?

• Someone outside the doc team needs to handle the technical side, so you still have time to do what you do best: write user documentation. In our case, besides IT, one of our senior developers ended up learning more than he probably wanted to about MediaWiki. He made the wiki the source for context-sensitive help for detected issues; each of these wiki pages allows you to switch from English to Japanese. Some of our users have no access to the internet, so he also wrote a script that exports the wiki to static html for packaging with Klocwork software.
• Read blog entries like Tom Johnson’s Ramping Up on MediaWiki to remind you that you’re doing the right thing.
• When the voices in your head whisper that it’s impossible to both switch your help delivery mechanism and reorganize/rewrite the entire help system in just a few months, take a pill or something.
• When your inner perfectionist rears its ugly head, repeat this mantra: The wiki is never done. The wiki is never done.

In the end, despite feeling like we were being drawn kicking and screaming into the gaping maw of hell, we love our wiki, and we hope our users will too. And users, if you don’t like it, you can change it!

Agile technical writing is a popular topic in the blogosphere (see Edwin Dawson’s recent three-part blog series). The user communication team at Klocwork is becoming more agile in fits and starts. In the last release, we joined our development team in using Xplanner, and found that it both reduced that horrible did-we-miss-something feeling and increased the visibility of our status.

In this release, we’ve resisted the urge to create a matching help story for every dev story. Instead, we create stories that allow us to focus on the highest-priority types of information: what’s new in this release, how the system works, how to get started, and how to use the tools day-to-day.

Our biggest struggle with Agile right now is how to stay on top of feature development while working on our own help-specific stories (like the current crazy-making idea of moving our help to a Wiki). Here are a few things we’ve learned along the agile way:

• “Just barely good enough” can mean documenting a feature only in the “What’s New” guide in an early iteration. This forces us to understand the “why” of a feature. It’s easier to ignore the “why” when you’re writing step-by-step procedures. Later, we’ll add information on getting started, a detailed how-to, and any necessary reference information.

• Workflow is king. If we don’t know how users will incorporate a tool into their environment and use it day-to-day, there’s no point writing a lot of words about which button to click when. So we push for details on workflow. And once a few customers provide feedback on a proposed workflow, the how-to starts to write itself.

We’re hoping these ideas will help us forge enough of a path through the agile doc frenzy to retain our sanity through the release.

Tom Johnson’s recent blog article (a must-read, involving ice picks and eyeballs) reminded me of one reason we want to move Klocwork’s user communication content to a Wiki: we want to talk to our users. Crazy idea! Let the doc team talk directly to the users? What stupid things might those literary types say?

I confess that it’s taken me a long time to get to this point. Johnson says tech writers are often subject to figurative lobotomies, like “don’t bother the subject matter experts; they’re busy”, “don’t use your own voice on video tutorials”, and “don’t talk to your users”.

So we’re crippled from the start, and some of us take years to discover that we produce the most helpful help when we become more of an investigative journalist, actively engaged with those who create and test the tools and those who use them. (It seems fitting at this point to mention that one of the writers on the team is a former newspaper girl who recently created a video tutorial for Klocwork Solo, using her own voice.)

I’m also inspired by Sarah Maddox, who regularly blogs and tweets on tech writing, especially on using Wikis for user documentation, chatting with customers about the tools she documents, blurring the line between documentation and product management.

So, we’re going to expose our soft underbellies. We want to hear from our users directly, rather than the usual generic rants transmitted through our product managers (a recent example: “Need better documentation”). When you rant to us, we’re going to want details. How exactly is the help not helpful? What page made you throw up your hands and curse us? And telling us what works can be just as effective as telling us what doesn’t.