You just might find...You get what you need

Sorry, I've had the Rolling Stones rattling around in my head all evening; hence the title.

A lot has been said about the Society for Technical Communication lately, so I trust you to forgive me if I don't beat that dead horse. Instead, I'd prefer to flog one of my own favorite equine corpses, Getting What We Need From The Software Guys.

Late last week I started what I thought would be a minor update to the product help for MumbleCo's flagship product, Big Software. One of the changes was that things had been streamlined. They had eliminated all cases of multiple paths to one task. Excellent! I slammed through all the task topics in the help and updated the navigation. Easy-peasy.

Except...

As I updated the top-level navigation in each task topic, I realized that in addition to the top-level changes in the software - tabs moving from one place to another - the entire user interface had been streamlined. Just about every gol-dang screen. Gone were the buttons that hid drop-down menus; now we just had clickable links right out in front of God and everybody. Extra clicks had been removed from nearly every task. This was a huge improvement in usability, but suddenly the help update stopped looking minor.

I have worked with many technical writers who would have stopped right there and gone up in a tight spiral, yelling variations on "How could they do this to us?" You know the routine.
"Why didn't they tell us they were making this change? Are they TRYING to mess with us?"
"OMG, they never tell us anything!"
"Code guys are so self-absorbed!"
And my favorite, "They have no respect for WOMEN!"
I skipped all that. Here's why:

Taking all these gripes in reverse:
I'm a woman, and no developer has ever shown me disrespect. So I have doubts about the whole misogyny thing. Next!
Developers have their own priorities and their own way of seeing the world, just as technical communicators do. Next!
They never tell us anything - OK, do we ever tell THEM anything? Such as how we work, what we need, what our schedules look like? Generally, not until we fail to get what we want. Next!
They didn't tell us about this stuff because it looked pretty trivial to them. Why should they bother us over something as trivial as taking a pull-down menu and making all the choices visible all the time? They don't know how we work, so they don't realize that's important to us.

So I skipped the yelling step and went straight to the next one - solving the problem.

The head of the software development team walked by my desk at an opportune moment. I hollered his name: "Code Jedi!"
"I didn't do it!" he yelled back, speeding up.
That's my line, but I didn't call him on it. "I know you didn't, and that's the problem," I hollered back.
That stopped him. "What's up?"

I explained that I needed information I hadn't been getting, and that I knew the reason I wasn't getting it was because Code Jedi's team didn't know that I needed it - I hadn't ever asked explicitly. As a consequence, I was trawling every single task topic in the help for Big Software to check it against the Big Software user interface, because a lot of things had changed while I wasn't looking.

I explained that while the changes streamline the tasks that people do using the software, those changes make the help inaccurate. People who are comfortable with software in general won't be troubled in the least by the changes, but those are not the people who resort to the help. If I don't know about a change in the sequence of things that people have to click, then the people who rely on the help to build their confidence will have that confidence shattered when the help doesn't match what they see on the screen. So I need to know about even tiny changes in the user interface. If it's connected to a reported issue, I'll find out, because I work from the issues tracking system just as the software development team does. But if it's so minor that someone fixes it on the fly, I may not find out.

Code Jedi got it. All of it.
"First of all," he explained, "We don't do ANYTHING unless we're told to do it. So it doesn't happen unless it's connected to a reported issue. But you're right that we're not giving you the information you need. What we can do is put a check box in the issue reporting form, to flag whether the fix affects the user interface."

"That sounds good, but what I'd really like is before-and-after screen shots."

Code Jedi thought about that. "That would be hard. The developer would have to have access to before-and-after environments. Or they'd have to remember to do the screen shot before they started."

"OK, I could probably get what I need if I could just get an 'after' screen shot reliably."

"We could do that. Make the issue tracking form include the checkbox that flags a UI change, and attach a screen shot if it's checked. That would not add a lot to the guys' workload. We could do that. And QA could check whether the UI changes and bounce the issue back if one of my guys forgets to attach the screen shot you need."

OK. That would give me everything I need.
It took five minutes of friendly conversation to devise a process to ensure that I always get the information I need. "Thanks, Code Jedi. There will be chocolate-chip cookies in the near future."

"Awesome."

Problem solved.
And I've got all the ingredients for chocolate-chip cookies on hand.