Jason, thanks for being a great technical writer. You were on many Annex Consulting Group contracts because you are excellent at your craft. I trust you will stay busy for many years to come.
—Stacey Cerniuk, President & CEO, Annex Consulting Group Inc.
The following somewhat (but not entirely) fictionalised story commemorates a failed attempt to impart upon a decision-maker the benefits of single-sourcing technical content.
A 30-day free software trial of Madcap’s Flare software seemed like the way to go to get us out of the tired rut of our end-user technical documentation. This product’s offerings of single-sourcing capabilities included content tagging for advanced cross-referencing, sophisticated importing and exporting, team collaboration (with multiple levels of access for reviewers), and most of all, topic-based structuring.
Photo credit: MadCap Software, Inc.
When I met with the decision-making manager, his first question was why I needed 30 days. “Well”, I said as diplomatically as I could, “I don’t expect to be assessing the software 40 hours per week for 30 days. That’s just Madcap’s trial period.”
But that was just his warm-up because he seemed to have other plans in mind. “Before we start looking at new software”, he said, “perhaps we need to step back and assess what our users need.” Normally this would seem like a reasonable suggestion, but to date no interest had yet been shown about user needs, so why now? I suspected a delaying tactic.
The manager offered to run some analytics on traffic for our Webhelp and maybe even send out a survey to all users so as to solicit their feedback on the documentation. The manager seemed confident that something would come of engaging our users, although I already knew that we had very little data on usage and that it would be very easy to draw whatever conclusions we wished from analytics. If this is the requirement needed to install a 30-day free trial of software, I thought, why bother?
“Have you thought of using WordPress”, the manager queried. I made a point of not letting my emotions show, but some part of the cheery recommendations I was planning died in that moment. “No”, I said but added quickly, “How would you implement a single-sourcing solution with WordPress?” The manager waned in his enthusiasm a little, so I took the opportunity to explain the problem/solution further.
“We have a large array of documents (user guides, training handouts, change management documents, release notes, and on and on) all of which are maintained in a way that creates great inaccuracies and much wasted time keeping track of revisions and duplicates.”
By mentioning the problem with duplicates, I thought I’d laid down a trump card of sorts, but the manager took it to mean that I was prey to some form of technical writer magical thinking.
“There is no software that’s going to prevent duplicates”, he said, “People, no matter how great the software, can still create duplicates.”
I had to pause at this. I wasn’t proposing a magic bullet. I knew full well that software has limitations. I needed an example to put him squarely in the seat of what the present system is like and why it isn’t working.
“When you drive down the road, there’s nothing preventing you from swerving your car into oncoming traffic”, I went on, “You can do it, but what’s preventing you is your agreement (coupled with myriad laws and cultural taboos) to play within the rules.”
“Of course, people can still create duplicates, but what we need is a set of tools that point us toward good practices rather than the current system (Word documents stored on people’s C drives) that get copied, and copied, and pasted, and then re-copied across the system in a way that’s prone to error. Then, if there’s a change to be made, who can find all the documents affected and change them?”
The manager conceded my point, but then he went off in another direction to question the need for documentation—AT ALL!
“Do you have an iPhone”, he asked.
“Yes”, I replied.
“Did it come with a manual?”
“Well, yes it did”, I confirmed suspecting now where his questions were leading.
“Have you read it?” This was his turn to sound triumphal.
“No, I haven’t”, I said.
“You see!”, he erupted, “You have an iPhone and it has a user manual, but you’ve never read it!” He seemed almost delirious at this portrayal of software so intuitive it didn’t even need a user manual. Clearly, Apple in its magnanimity was providing user guides only as a form of self-effacing humility.
I thought it wise to choose my words carefully, so I paused. And then I said, “It’s true. Since I came to your software company, I have worked on the assumption that we all agree that there is a need for software documentation.”
Then I launched my final salvo.
“When your software is designed to Steve Jobs’s and Apple’s standards—that is, it’s so intuitive no user guide is needed—I’d welcome the idea of dropping documentation. But I’m working with the system as it is now.”
I have very much appreciated working with you and having you on the team. The work you have contributed to does make a significant difference for the product and our business going forward! I believe we have raised the bar at BCLC and hopefully this will encourage others to take their products / businesses to this level.
I have personally learned a lot working with you and have very much appreciated having you around for the past year on our team—your final gift—you have articulated exactly the environment I strive for creating as a professional: “Relaxed Productivity”. I love it! That’s going to be my new mantra.
—Nathan Kulczycki, Product Manager, BCLC
Yesterday in our working sessions with our inter-provincial customer, they complimented the product document suite. Not only are they starting to realise what a powerful set of documents it is for them, but they also said it presented a really professional image for our product — in fact, they asked if our actual product was as mature as we’re making it look. Great work!
—Jon Chapman CEng PMP , Project Manager, BCLC