Cures for the Information Exclusion Complex

by Tom Johnson on Feb 8, 2010
categories: technical-writing

Some years ago, I used to suffer from developer neglect, or to use a more scientific term, from a kind of information exclusion complex. You know what I'm talking about. Developers make updates to the interface, often at the last minute, and don't let the tech writer know what changed. As a result, the help is wrong and out of date. It's a frustrating experience from the writer's perspective.

Information exclusion is fairly common. Just last week I learned about an application that had a new version nearing release in a week, but the developers hadn't told me about it. I documented the previous version, and although the developers made the help button more visible, they never told me they were releasing a new version. They never mentioned to me what they had updated.

In their minds, they hadn't updated much. A few enhancements here and there, but did any of it affect the help? They didn't know because frankly, they probably never read the help. In their minds, help had been checked off the list weeks ago. There was no need to revisit it. Besides, they were mostly working on bugs and fixes, not new use cases.

When I learned, through a general department meeting, that a new version of the application was being released in a week, I scrambled back into the application to find out what had changed. As I moved from topic to topic through my help and the interface, I spent the next 30 hours making updates to the help content. I had to scrap all of my videos, as they were no longer accurate. I added some new topics, removed others. Fundamental terminology changed, and new functionality had been added.

As I sat there updating the documentation against the clock, I could hardly believe I hadn't been notified. C'mon, were they really going to release this without telling me what needed to be updated in the help?

I was a bit upset for a few days, but under too much pressure to really think through the why of the situation. Instead, I was heads-down, hands on the keyboard, frantically making updates and logging bugs and trying to fix things before they shipped it out the door.

Though I tried not to think this way, I started to resent the project manager a bit. I had rarely been invited to a project meeting or scrum. I had to persuade the project manager that their app needed comprehensive help in the first place. Wasn't the project manager savvy enough to know that with each update to the interface and functionality, the help needed to also be updated?

This is a situation you've probably run through dozens of times. Once early in my career something like this happened -- the interface kept changing on me, and no one ever informed me about the changes. One of my senior colleagues looked at me and said, with a smug look on her face, "Welcome to our world."

In those early days as well as the other week, when I experienced developer neglect and suffered a lack of information, I felt marginalized. I tasted the second-class citizenship status that so often takes place in IT organizations with technical writers. The tech writer is the last to know about interface updates, if anyone even bothers to let him or her know.

The perception of information exclusion, whether real or not, is so common among technical writers that it might even be classified as a complex. If you suffer from an information exclusion complex, you're disgruntled at project teams for not telling you the information you need to do your job correctly. The project's information door has been shut on you, and you must kick your foot under the door to wedge it open.

Well, I have started to figure out how developers tick, and I recently discovered something that has helped me break free from my information exclusion complex.

How Developers Tick

I didn't piece this together all at once, and it is still a picture that is forming in my mind, but it's compelling. At the heart of how developers, quality assurance (QA) engineers, and project managers interact is through a bug/enhancement tracking system called JIRA. In your organization it may be something else, but the concept will likely be the same.

In my organization, every time QA engineers find a bug, they log it in JIRA. Every time project managers have an enhancement to the existing functionality, they log it in JIRA. Every time developers fix something, they log it in JIRA. Every change to the application gets logged and tracked in JIRA.

The project manager and QA lead assign the items in JIRA to developers. Developers and QA comment on each of the JIRA items, noting challenges or obstacles to the JIRA item. Project managers give each JIRA item a priority level, so that P1s get the most critical attention, while P3s are usually not worked on at all. In short, JIRA stores all of the necessary information for the project.

I have simplified things here, because even though all important and changing project information is stored in JIRA, the JIRA system itself is like a maize to navigate. In one of my projects, we have nearly 2,000 items in JIRA, all with various priority levels, version release assignments, sources, dates, comments, and other details. Navigating JIRA can be like looking at a street map of Mexico City and trying to decide where or how to go.

Despite the challenges, keeping up with JIRA, I've learned, is the key to staying on top of a project. It's how the developer mind works. Once you understand this, it will help cure all symptoms of the information exclusion complex. If a developer logs something in JIRA, whether it's a bug, a fix, an enhancement, a user story, or even an update the server the application runs on, he or she expects that everyone else on the project who has access to JIRA will see the update. The developer assumes everyone is as JIRA-savvy and JIRA-driven as he or she is.

As technical writers, we often scorn users who are too slow/lazy to read the manual (RTFM). The corollary for developers is to scorn technical writers who are too slow/lazy to read JIRA (RTFJIRA). See how the tables are turned?

Leveraging JIRA to Influence Changes

Don't be intimidated by JIRA, or whatever bug tracking software you use. JIRA is your best friend, because now that you know the secret -- that JIRA controls all information about a project -- you can start to leverage this information source to influence updates and changes to the application as you see fit.

You know that capitalization error on the home page of your app that is driving you nuts? Stop complaining about it in project meetings. Just log it in JIRA and it will probably get done. How about the error message box that says, "Object reference not set to an instance of an object." You've been telling developers for months that no one will understand it. But they aren't waiting for an email from you to specify how to fix it. No, they're waiting for the item to appear in JIRA. Like a cook waiting for an order, developers will simply see the request on their screen and get to work.

Not every thing you slip into JIRA will get implemented. The tough fixes will be procrastinated, just like you have procrastinated the toughest help topics in your help. When developers feel weary and tired, and when they're winded from playing too much ping pong, they'll cherrypick the easy JIRA items that require nothing but simple text updates -- your capitalization pet peeves, the label misspellings, those inane on-screen messages that developers typed while they were half-asleep. As long as you stick your requests in JIRA, they will eventually get done.

Still a Few Surprises

Although I'm following JIRA more carefully now, I still get surprised by project release dates I wasn't anticipating. But this is only because I fail to check the project items and statuses. Lately, however, I have subscribed to the RSS feeds of the comments and issues in JIRA I want to track. (By the way, RSS Bandit is one of the few RSS readers that can pull authenticated RSS feeds behind your corporate firewall and send you updates when additions are made.)

Even if I'm surprised every now and then by unanticipated changes, I've completely shed the information exclusion complex. I'm not frustrated if developers don't tell me about interface and functionality changes. In an agile environment, there's no way they can keep me updated on an individual level about everything that changes. And I wouldn't want them tapping on my shoulder all day anyway. I can learn most of what I need to know just sitting in my chair, looking at my screen, submitting new items to JIRA or looking at those JIRA items that have been submitted. Every once in a while I drop by the developers' desks, but more to say hello than to ask what's new.