The term ‘hockey fan’ does not apply to me. I simply cannot spend three hours watching a group of people skate around trying to insert a small, flat rubber cylinder into a mesh. (Hockey fans, please send all hate mail to firstname.lastname@example.org)
In a Tech Writer’s World, I am the “thinking man’s” interviewer on the Sports Network, conversing with fans after a game:
Me: So, how do you feel about our team winning tonight?
Deranged hockey fan: Oh man! It’s awesome!! Wooo-hoooo!
Me: So you’re excited about the fact that a bunch of millionaire-strangers who don’t want anything to do with you were able to score more points than another group of strangers: how does this victory affect you on a daily, practical level?
Deranged hockey fan: Uh – go Leafs!!!! Yeah!!!
Me: Another insightful comment from the sports drones. Back to you, Frank.
Now, this is not to say that hockey games cannot be exciting. However, what generates this excitement is not so much the actual play, but the running commentary. In fact, we should have commentators for the documentation review process:
Announcer: Joseph generates the first draft. He passes it off to Andreychuk. Andreychuk toys with it, marks it up a bit, slides it off to Curtis, Curtis tries to read it, he can’t, slaps it over to Belfour, Belfour marks up a procedure, adds an overview, passes it over to Kariya, Kariya misses it, ends up with LaFleur, LaFleur makes some more changes, passes it back to Curtis, he still can’t read it, he shoots it over to Turgeon, Turgeon doesn’t want it, passes it back to Curtis, back to Turgeon, to Curtis – boy these guys really hate reviewing drafts – Curtis finally shoots it over to Dwyer, Dwyer’s holding it, looks like he’s scribbling something on it… let’s zoom in the camera bit… Looks like he wrote: “needs work”…ooooo.. the ref’s not gonna like that…
Referee: Penalty for number 32, Ken Dwyer – 10 minutes for vagueness and poor spelling…
Announcer: That’s gotta hurt. I always said he wasn’t a first draft player…
Still, as much as hockey itself does not interest me, the current labour dispute does interest me. In fact, for the first time in my life I actually find myself religiously reading all hockey news in the sports section of the newspaper. The idea of two sides, so tremendously apart, so unwilling to budge or compromise, so willing to drill holes through the other side’s boat, not realizing they are all on the same boat, is endlessly fascinating. And if I, a non-hockey fan find it fascinating, then people who are hockey-fans must be experiencing severe rupture of most of their internal organs.
So, you’re not a fool if you’re not interested in this dispute. But you would be a fool if you failed to learn the lessons from it:
Lesson 1: Terminology is everything.
One of the problems in this battle is that the two sides cannot agree on the meaning behind the specific terms in the negotiations. When you have one side saying that a specific proposal is a “salary cap”, and the other side saying it is not a “salary cap”, this doesn’t mean one side is “right” and the other is “wrong”. It indicates that they cannot agree on what a “salary cap” is. Is it a limit on what all players can make in the league? On what an entire team can earn? Is it, for practical purposes, a number so large that it could never be reasonably reached? Is there a time constraint on it? Can there be exceptions?
Documentation and software development face the same problem. An item or object in a program may go by different names. The same name may be wrongly applied to more than one item. What an item is or does varies depending on which SME you talk to. This leads to endless confusion and frustration for both technical writers and end users. One of the most important tasks in the documentation process is to clearly and consistently define what all elements are. Glossaries help tremendously in this task, which is why they are often very difficult to develop. You may find yourself having to forge many different opinions into one document, but the end result is a “rule book” that everyone can use when referring to the application.
Lesson 2: If something stops, it is forgotten.
The level of contempt most people have for both sides in the hockey dispute is palpable – you could cut it with a hockey stick. “Millionaires arguing with billionaires” is how this fight has been described.
What is happening now is quite remarkable, completely predictable, and the worst nightmare imaginable for both parties: people are beginning to getting used to the idea of no hockey. They are actually finding other things to do with their lives. I remember a few years ago, during other labour disputes, when neither hockey nor baseball games were taking place. In a letter to the editor, a father indicated he actually didn’t mind the dispute because it allowed him to spend more time with his family. Horror of horrors! What’s next? People might start meeting with their friends, reading, or god forbid, writing columns like this one. It’s just too painful to think about how far our civilization could advance if there was no more hockey to watch.
Doctors tell us that if you do not keep your muscles moving, they will atrophy, or grow weak from non-use. It took years for baseball to recover from its labour disputes, and it could take hockey even longer.
The lessons for technical communicators are two-fold. On an individual level, we must continually hone and expand our various skills. These include not just writing, but learning new tools, organizing, project management, SME interviewing, as well as general career management skills such as networking, job interviewing and resume-writing. As with hockey, we can never rest on our laurels; we must be continually moving, learning and adapting. Otherwise, we will atrophy.
On a company level, we must continually fight to show we are indispensable. Many companies would like nothing better than to get rid off all tech writers, QA workers and half the programmers. The only reason they do not is that they believe it would cost them more in the long run. We must be the ones to convince others that we are indeed indispensable, that unlike hockey, a company would never “get used to” having no tech writers; that this would create unimaginable pain for them, in the form of higher support costs, poorer documentation (if there still was documentation!), lower quality software (because we are no longer there to give objective feedback on usability), grumpier customers, lower sales, and ultimately, lower profits. We can make our case not just by improving things, but by showing those in power how we have improved things.
Lesson 3. Some things are so broken, they can only be replaced.
Most experts agree that if hockey does return, it will be a very different game under a very different league structure. In fact, it may be completely unrecognizable from its current form. Often things are so damaged, it is not even worth trying to “fix” them, but is cheaper and easier just to replace them.
A vivid example of this involved a car I owned which was in an accident. Thankfully, I was not a passenger, and no-one was hurt. I thought there was only minimal damage to the car – a dented front-end, and two released air bags. I was fairly confident the car could be repaired. To my surprise, I discovered it was cheaper for the insurance company to pay me the replacement value of the car rather than fix it.
Hockey was always running on borrowed time. The various tweaks and repairs did nothing to address the underlying problem: more money was being spent than generated. No business can operate indefinitely under such conditions: witness the recent JetsGo fiasco. When such a state exists, the company must be put out of its misery like a mortally-wounded animal. If may be resurrected, but only as a completely different company.
Macros Under a Microscope
This lesson applies on both a micro and macro level to documentation. One of the greatest struggles we face is updating existing projects. Sometimes you can get away with making specific changes, updates and tweaks. However, other times the original document is so outdated, and the changes so vast and so numerous, that it is not worth it to salvage it. You may have to rewrite an entire chapter, or even the entire manual. It can be easier to create something from scratch rather than trying to fixing something that is so thoroughly broken.
On a macro level, this principle applies to the entire information development process. As I’ve indicated in previous columns, we are experiencing a revolution in how documentation is created. We are reaching the limits of traditional documentation constructs: pages, chapters, books, and so on. These traditional “broken” systems are slowly being replaced by object-oriented documentation and content management systems. The effort required is incredibly expensive and time-consuming, but is the only long-term solution to effectively manage huge volumes of information that are overwhelming companies and information developers.
Lesson 4. Without compromise, nothing is possible. With compromise, anything is possible.
This is the final and most important lesson of all. Everything in the world that is created, including man-made objects, cities and countries, and even people (including you, dear reader) exists only as a result of compromise. Take the computer monitor you are staring at right now. At the company that manufactured it, there was probably one group that wanted it to be larger, another that wanted it smaller, another that wanted it to have more features, another that wanted less features. Every aspect of this monitor was debated, argued over and ultimately settled as a result of compromise. And as a result, you are now staring at this monitor. Don’t you just get a lump in your throat thinking about it?
Unfortunately, compromise seems to be the furthest thing from both sides in the hockey war. Yes, both sides did move quite a bit before the final breakdown, but it was too little too late, and neither side followed through. Since both sides appear unwilling to compromise, they should have agreed to binding arbitration, where an outside third party examines all the financial information, listens to arguments from both sides and then makes a decision. But agreeing to binding arbitration itself requires compromise, which was already in short supply.
Good documentation (like everything else) is built on compromise. No software or document ever released is perfect, complete and without error. It can always be made better, if customers don’t mind spending an infinite amount of money and waiting forever for it. At some point, development must stop, and the product and its documentation must be released, warts and all.
One of the more interesting meetings I have the privilege to attend are “bug reviews”. Myself, the project manager, the product manager, the developers, QA and others secretly gather in a locked, darkened room, lit only with candles, to discuss the current defects (or “bugs”) found in the application. We discuss each defect in turn, and often there is lively discussion about what to fix. Ultimately, the project and product manager decide the course of action to be taken:
1) Fix the defect.
2) Postpone the defect.
3) Document the defect.
All Hail the Documentation Emperor
That is, the managers decide which defect shall live and which shall die. It is all quite dramatic and reminiscent of the way, in ancient Rome, after one slave would battle another for sport, then the Emperor would give a “thumbs up” or “thumbs down” to indicate whether the losing slave should be killed or spared by the victor. Imagine how boring the death games would have been if a committee had been charged with making the final decision.
Ultimately, we must all become Documentation Emperors. We must fix what we can in the time allowed and compromise where necessary, but then must decide which documentation defect shall live, which shall die, and which can be postponed.
Compromise followed by solid action can save any documentation set, and will ultimately save hockey. If not, you can always watch curling!
Thanks to Bernard Aschwanden for the inspiration for this article.