Cures for the Information Exclusion Complex
February 8th, 2010 | Posted in blog 17 Comments »
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.
Sponsors
Tags: accuracy, jira, quality assurance, subject matter expert, Technical Writing, update
If you liked this post, keep updated with new content: Subscribe to I'd Rather Be Writing.
Both comments and pings are currently closed.
3613 Subscribers
Mark Baker (7)
Greg DeVore (4)
Jonatan Lundin (4)
bg (3)
Marcia Johnston (2)
mma (2)
Tammy P (2)
A Andrew (1)
Aldergrove drivin... (1)
B.J. Smith (1)
Tom, you definitely struck a chord here. Suffering from “Information Exclusion Complex” is something we all experience sooner or later. But your tip is very valuable!
Our developers use Visual Studio Team Server as tracking and source control center, but I assume JIRA is quite similar.
I actually use Visual Studio already, not only to keep track of changes and to log feature requests myself, but I also generate a list of all changes just before a product is released, to incorporate that information in the Release Notes.
I even made a deal with the developers to label each change they check in with a “Bugfix”, “Change”, “New” or “Internal” label (where internal means that the change may not be listed in Release Notes). This way I’m sure I don’t miss out on any changes in the applications ànd I instantly know what the new features are, what has been changed and which bugs have been fixed.
Sounds like business as usual where I work. I’ve gotten used to it.
Tom, this one’s spot on… Happens all the time here, despite the various methods we have for making sure it doesn’t. One thing that helps: we re-install the latest software build daily and check for new changes. We have systems in place similar to JIRA (and use that, too), for various types of issues.
I’ve never thought of it before, but you’re right. It IS the TW equivalent of failing to RTFM.
Good topic, Tom. When my current company adopted the scrum methodology of agile development, I was very lucky to get included in almost every aspect of the process. I’ve found that the daily “standup” meetings have been the best remedy for IEC. When a developer reports “I fixed a defect that…” it gives me a good chance to follow up and find out whether it’s a user-facing change.
Not to say that this doesn’t happen at all any more, but certainly a significant amount less than it did prior to our process change.
I’ve found that our defect-tracking software is a tough place to keep up with such changes. Perhaps it’s a bit of laziness on my part (it can be tough to wade through dozens of defect/enhancement items), but there are also often times that the defect report is misleading or incomplete. Based on the report, I might think that the change was solely behind-the-scenes when, in fact, it was user-facing.
Oh, my, yes. I’ve been there. Great article, Tom.
In addition to keeping tabs on what’s in JIRA, perhaps you can convince the engineers to add a field to the form they use when creating or updating an item in JIRA. It could be labeled “How does this affect the user experience?” and it would encourage the engineers to at least pause and think for a moment about the user’s point of view. By tracking this field, you can keep tabs on changes that might affect your help documentation.
This goes a bit beyond the Bugfix, Change, New, and Internal labels that Siska Moens mentioned, but it won’t saddle the engineers with a lot of extra work. Its purpose would be to alert you to potential changes, not necessarily to describe changes in exhaustive detail.
Excellent post this morning – was having a lengthy conversation on this very topic (although I wish I’d come up with “information exclusion complex.”) with a couple of other consultants this morning when discussing roles and tools in the agile process for a client project we are working on.
You hit the nail on the head here, Tom. Nice!
As the saying goes, “When in Rome, do as the Romans.” If a bug-tracking tool is what developers use to determine their work schedule (we use Bugzilla), then make sure to get your tech writing requests into the tool!
Your point about having project managers use the tool to track feature requests is something that doesn’t really happen around here. I’ll suggest they log their requests into the tool as well, so it can be tracked, managed, and viewed by all involved parties (PM, Dev, QA, and tech writers).
Thanks again!
Yeah, it doesn’t quite work out if everyone isn’t using the system. Our PMs add user stories to JIRA. But I do admit that in the initial design of the application, not every user story is added to JIRA. Just the main ones. The prototypes have a lot of detail not explicitly stated as a user stories.
Another good way to track these last minute updates is to be a part of QA team (besides being a TW). That’s what I am doing right now.
nicely narrated, good post TOM.
Thanks Regaraman. I like that you’re flexible enough to wear multiple hats on a project.
I actually have the opposite experience with UI text changes that I log in JIRA. The customers prioritize the bugs, so the high-priority ones get done first (makes sense, I guess . . .). My text change bugs are the absolute last thing to get done because they’re P3s, unless the customer agrees that the text is confusing and needs to be changed. But a capitalization change? Forget it. That bug will never get to the top of the list.
So I take the politician’s approach and package my little text change in with a related bug (JIRA pork?) so that while the developer is working on the original bug, he can make the text change. Or if there’s an enhancement to existing stuff, I ask the developer to correct the text. No big deal.
But I have also been awakening to the effectiveness of using JIRA to keep up on changes and know the status of stories and bugs that are scheduled for a specific release. It can certainly help us feel less like victims of the complex.
Ben, thanks for the tip about packaging small fixes in with larger ones. That’s a good strategy. I’ve found that a lot depends on the project manager. Some PMs don’t think tech writers belong in JIRA at all, while others open the doors wide and invite you to start logging everything and anything. Like you, though, I’m becoming more and more awakened to how central JIRA (or TFS) is on a project. We should really be in there from the minute we join the project.
Tom, after reading your post, I figured I’d better check the portal I mentioned in my comment (above)… thirteen entries! Thanks for the push.
Back to my keyboard….
Tom,
Good post.
However, I was actually surprised that you mentioned that you were never invited to a scrum (for a couple of reasons, actually). In scrum, you’re not supposed to need to be invited. Actually, scrums are supposed to be open for anyone in the company to attend (although only the actual team members can speak at them).
We use Jira as well. I totally agree with you about it being a beast to navigate. I swear the workflow and navigation of that system was designed by M.C. Escher. As a result, I actually don’t use Jira. Also, our company doesn’t get very detailed in terms of requirements (which is basic to scrum and Agile), so I usually find them less than informative.
The best method I’ve found to do this to develop a relationship with the developers (particularly the front-end guys), and then meet with them informally as often as possible. Is this possible in your org?
Anyway, awesome post. I’m really interested to hear how things go for you.
-Dan
P.s. It’s also interesting to note that you’re not considered part of the scrum team itself. I’ve seen some groups have tech writers on the teams, some groups have them in their own department as support groups, or in my case, part of it’s own cross-functional team with the User Experience group (which works ahead and in tandem with development).
Dan, thanks for your comment. With some projects, I am intimately involved in all aspects of the work, and I attend the scrums, design prototype reviews, customer feedback sessions, user acceptance testing, and more. With other projects, I’m called in at the last minute to provide help content. In those cases, I’m never really integrated into the project. With 600+ IT people and about 4 technical writers, there aren’t enough of us to go around and be embedded in every project team full time. We’re still educating project managers around the need for technical writers embedded on their teams.
As well as having full access to the bug list, each morning I receive an email that lists all the fixes that where committed to the version control system the previous day. I can often recognize a GUI change by the three letter extension on files that were checked in. If something surprises me I can talk to the developer whose name is associated with the check-in. As the lone technical writer I am also part of the software development team and therefore get to attend most meetings with the developers.
heya, many thanks.