Pardon the imposition . . . . Step up when documentation doesn’t determine the tool

Home/Publications/CIDM eNews/Information Management News 01.14/Pardon the imposition . . . . Step up when documentation doesn’t determine the tool

Chris Bridgen, Alcatel-Lucent

Integrating a new software tool into the workplace can be fun, right? Smartphone in hand, you get to read breathless product reviews over lunch. Then you begin more pointed research. If you’re lucky, off you go to a conference or expo (maybe CIDM’s spring conference), followed by a lot of demo version installations and playing in a dozen sandboxes, all while plastering sticky notes over your calendar to keep those 10-, 15-, and 30-day trials in neat order.

But what if instead you find R&D simultaneously trumpeting and dumping a new tool on you? Surprise! And congratulations. You have the opportunity to both increase your skill set and impress subject matter experts on their own playing field.

This happened to our documentation team after a product development team fully embraced—seemingly overnight—agile development methods. As part of their group hug, the designers adopted Jira as a requirements management tool and the Jira plug-in Confluence as a wiki system to replace Word-heavy waterfall specification documents. Jira is the truncated version of the Japanese word for Godzilla. How very appropriate.

Their message about this change to us in technical communicators was blissfully succinct: “Hey, here’s the link.”

Thanks. So we clicked. And clicked. And then we clicked some more. Others were invited over to stare at the monitor. And that huddled group watched as our current processes were swept away, replaced by a whole lot of unknown, a brave new </world> with neither map nor compass in hand.

Here’s what we found, what we did, what happened, and how it ended.

Go With the Flow

So when you’re thrown in the deep end of the pool, swimming seems like a sensible response. Unlike flailing youngsters, we possessed the skills, product knowledge, composure, and process understanding to know what had to change. No question it was a challenge. Teams had better like challenging, especially in an evolving workplace. Presenting this as a challenge to your team, while staying composed yourself, goes a long way to relaxing nerves.

It was no time to try and force R&D to shave Jira into the shape we needed. Deliverables had not shifted to accommodate us. We pared down our processes to essentials and flexibly fit into this new shape—all while meeting the stringent quality criteria of a TL 9000-mature product organization. The new process was assembled quickly, sketched via email, and approved in a single meeting. Product managers murmured appreciatively when they saw us adapt. In what looked like a very agile way.

We chose to become more modern in our planning processes. We took the chance to turn away from Word as the go-to tool for static project plans and instead we embraced the flexibility and on-the-fly responsiveness of Jira, with its built-in review workflow and simple version control management. My team learned that process is not written in stone, to be worshipped from afar. I learned that my team could rise to unexpected challenges. Most importantly, the product group and the product’s customers saw no difference in our documentation output.

Demand Equal Access

Don’t let the R&D team segregate either the documentation or the writers to a special section of the tool. Oh, the dreaded “Documentation” area. Not a neighborhood you’d want to buy property in. No one ever comes to fix the plumbing. If R&D integrates a plug-in—Confluence—that gives R&D a wiki to document the software, then get writers also to use Confluence. Simple and elegant. Wikis replaced specifications. The source information was still there and in a less rigid format that encouraged collaboration.

Playing along nicely pays a number of dividends:

  • You will receive the same level of support as that superstar designer because all bugs affect everyone equally.
  • A big neon ‘documentation’ sign pops up every time your team interacts in the environment, be it comments, feedback, input, review, or approval cycles.
  • A quick question about a quirk in the program is an IM away.
  • The writers realize they cannot fall back on old habits. They’ve come out of the cave and blinking into the sun of the 21st Century, and there is no retreat.
  • It is easier to collaborate on a wiki than a 220-page Word specification.

Limit the Damage

There are always SMEs that love tools. They love tools the same way some writers love serial commas. Learn where they sit. Buy them coffee. Remember their birthdays. Those are the experts that their peers consult. You need to consult them too, so demand equal access to their skills. Piggyback on any and all training or workshops. Subscribe to blogs about the product.

A major mistake to avoid is asking that certain functions—document planning requirements that are internal to the writing department—be retooled to documentation specifications. This is very rarely needed. Most of the time, retooling is merely padding to make writers more comfortable—putting those old seat cushions with the butt grooves onto a modern sleek frame. Not the right fit.

Conclusion

Was the change successful? Absolutely. New skills were learned, new partnerships created, and R&D continues to work side by side with documentation. In many ways, they now work as peers, with both groups realizing that the content generated and maintained using the tool is essential to customer success.

But I do check under the bed for monsters every once in a while.

About the Author
Chris Bridgen is a manager at Alcatel-Lucent with 15 years experience in telecommunications network management and hardware documentation. He is currently acting as strategist for the Customer Documentation department. He bet on Mothra and lost his shirt. This is adapted from the Jira Served Three Ways presentation at the April 2013 CIDM conference.

We use cookies to monitor the traffic on this web site in order to provide the best experience possible. By continuing to use this site you are consenting to this practice. | Close