Documentation is the castor oil of programming. The managers know it must be good, because programmers hate it so much. Gerald M. Weinberg

I used to be a strong believer in formal doc reviews. Distribute a draft, plan a meeting, and have everyone gather around the table. But in the last few years, my team has moved towards mostly meetingless reviews–because people hate review meetings (you know, like code reviews, only worse), because people haven’t always read the drafts when they get to the meeting, and because some of our dev team is overseas.

• First, we distributed PDFs and asked reviewers to submit comments in email or on a hard copy. For the overseas team, email was the only option. This is not fun for either the reviewer, who has to do a lot of copying and pasting and referring to page numbers, or for the writer.
• Then we tried Adobe Acrobat PDF reviews, which allowed all reviewers to comment on the same PDF and view others’ comments. This was a big improvement over the email method.
• Now that all of our product documentation is hosted on a MediaWiki-based site, we’ve asked reviewers to edit the pages themselves, or add comments to the Talk pages. This makes life much easier for both reviewers and writers.

Still, as Anne Gentle stresses in Conversation and Community, using a collaborative medium doesn’t guarantee that collaboration will happen.

How do we encourage developers and testers to “own” the documentation for their tools, and to think of help as part of the product? If we can get developers and testers to RTFM, the benefits are obvious. They understand the tools in a way that no one else does, so they’ll provide feedback that no one else can. And they’ll become familiar with the help for the tools they’re responsible for, so they’d know whether a change they’re making or testing would affect the help.

I thought up a few ways that might increase the amount of review feedback:

• Create review tasks in our Agile project tracking tool, XPlanner. A top-down approach, and I wasn’t enthusiastic about it. Kinda like the daily castor oil treatment.
• Make everyone’s MediaWiki user page into their doc review page; we’d add links to these pages and reviewers would be notified through email, then they could delete the link when they’ve reviewed it. A nice bottom-up approach, I thought, in the spirit of the wiki.

But encouraging collaboration may be less about tools and more about process. If we involve reviewers earlier, they can tell us what they think before we’ve written a draft. A draft takes a long time to review, and if a reviewer doesn’t like it, they might not provide any feedback at all.

As Donna L. Davis says in a review of Andreas Rüping’s Agile Documentation:

Documentation isn’t bad. But bad documentation is terrible.

Is reviewing docs worse than eating Brussels sprouts? Do you review docs when asked, or do you hide the invitations under the edge of your plate, hoping mom won’t notice? Is the help so bad that you can’t be bothered? Are you just too busy? Are you one of those people who never consults the help for tools you use? Do you think your users will be able to use the tools you’re developing or testing without the docs?

What would make you more inclined to “own” the help for the tools you’re developing or testing?

When I was documenting a new refactoring plugin for Vim, I checked out the Vim web site, and came across this blasphemy:

Vim isn’t an editor designed to hold its users’ hands. It is a tool, the use of which must be learned.

Later, someone sent me this beauty, from Elitist Jerks:

Stop being lazy and read.

Are users lazy? Do they expect hand-holding? Do they expect one button and no manual?

Or is this more true to life?

In the end, it probably comes down to this: Make tools usable. Then technical communicators can spend more time creating truly helpful help, and less time explaining a bad UI.

If our goal as communicators is not just great help, but a great product, Agile makes more sense than ever.  If we want our usability suggestions to be implemented, we need to get developers’ attention while they’re working on that feature. Find the rough edges that would require a lot of splainy-splainy, request a change, and then rejoice that we don’t need to explain what’s now obvious. Sometimes it’s hard for me to decide what’s a rough edge. Would my audience of developers find this as confusing as I do? But I’m learning to trust my gut.

At the same time, though I appreciate the benefits of Agile, I’ve started to worry less about the help being “done” at the end of an iteration; instead, I want to make sure I understand a feature well enough before the end of the iteration to suggest design changes and know what help will be required.

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.