The truth, the whole truth and nothing but the truth

As a technical writer you dedicate a large percentage of your time making sure that what you write is correct. I teach that if you cannot be 100% correct then resort to ambiguity, but never, never, publish something incorrect. True, ambiguous documentation doesn’t help anyone very mush, but at least it is not wrong, and depending on the level of ambiguity, the level of damage. Minor ambiguity can often be used since the intelligent user can work out what is needed. For example, if the button to close a dialog changes, dependent on circumstances from Cancel to Close, and you don’t want to describe all the circumstances because they are too obvious, stating something like “click the button to close the dialog” might be good enough, even if a little ambiguous.

While we reach for veracity, marketing writers have a reputation for wallowing in misdirection and partial truth, at best and downright lies at worst. Disraeli, at least according to Mark Twain, enumerated three types of lie: Lies, Damn Lies and Statistics, and the bread and butter of much of marketing is the use of statistics to prove how great they are.

Last week I had a discussion with one of the users of our products. The conversation was part of a program to meet, phone-to-phone, with customers to gain feedback about the documentation and where it can be improved upon. During one of these meetings the user mentioned that he was really surprised that the marketing material my company produces actual bears a striking resemblance to the truth. I have worked for this particular company, Zerto, almost since its inception and watched it grow from the fledgling to the beautiful peacock. At the forefront of this transformation was marketing, swallowing up large chunks of whatever monies the company managed to raise, to push the product. If the result is that the customer not only buys the product because marketing tell him it does what he wants and is the best in town, but then starts to evangelize about the product because it actually does what all the marketing hype says it will do, then something is right with the world.

I contribute little to the marketing effort, reviewing material as one of the stages the material goes through, as much so I am informed about the latest slant to push in the “proper” technical documentation as to actually correct any of the material I peruse.

Advertisement

You can’t always get what you want

After a thirty-six year wait I finally got to go to a Rolling Stones concert. True, they are not what they were all those years ago, but they are still pretty phenomenal.

Way back when, when I missed out, the ticket for one of the best seats would have cost me a fiver. I was a student and had been raised never to borrow money if it could be helped, so I didn’t borrow the then princely sum and forewent the opportunity to see one of the truly great rock and roll bands. 36 odd years later, even accounting for inflation I have had to spend around 6 times as much, based on what 5 pounds is worth today, for the same opportunity.

Of course my value system has also changed since those far-off student days and I am more appreciative of what I see and hear. So the Stones might not be what they were, but they are what they are and that is still great.

Their first encore was the great “You can’t always get what you want” – a refrain that rings true with many technical writers who feel that they always get the short end of the wedge. As Mick belted out the words, I thought about how we have to respond to the realities of life within the world of technical communication, and cope with being, at best, second class citizens, foreshadowed by the great developers and not so great everyone else. But the chorus doesn’t stop on a downer. Indeed, “if you try sometimes, you just might find, you get what you need”.

The Rolling Stones are creative. After over fifty years they wouldn’t still be packing 50,000-plus stadiums if they were not. And that is what we must be if we want to get what we need. Be it access to a printer or more commonly, more resources, that are required, try something out of the box and see where that gets you. I have recently started polling customers about what they want. I ask a few leading questions to get the answers I want, but these answers are very affirmative. So I am going to dedicate some of the limited available resources to creating quality, short video clips – just like the big companies do, but in my case it’s going to be done on a non-existent budget. The hope being that if these clips are successful, the demand for them will grow and the company will recognize a need to provide the resources to meet this demand in real time and not just as a hobby from that mad Englishman sitting in the corner sucking the end of a pencil.

I have argued in the past that technical writing by definition is not overly creative: Lay out each procedure like the previous one; use the same terminology instead of changing every so often to spice up the writing, etc. However, providing good documentation while subjugating creativity is in and of itself creative. So, we are a creative bunch of professionals and need to channel that creativity into new ideas to get us what we need.

 

You’ve been committed

I have a friend, hard to believe I know, who also has a blog. He frequently posts about his favourite topic, tax. Now this might seem like a really boring topic to post about, and I dare say in many hands it is, but Tax Break tends to add interest, most of the time, to even this tedious topic.

After reading his last blog, I automatically accessed my site and for the first time in a couple of months looked at my stats, expecting to see a sharp falling off as my regular followers give up on me and the random accessors start to tail off. Well you could have knocked me down with a feather, but my numbers were stable. So without doing anything my adoring fan base has remained true.

What does this tell me? One of two things:

• I have enough verbiage of interest to interest someone, somewhere all the time.
• Once committed to paper, or in this case the ether, whatever is said is committed forever more and available forever more.

This means that even if I wanted to stop, and a post every two months is getting close to this, my words live on. Once committed to the ether, someone, somewhere can find them.

This is true also of the documentation you produce. Or the training materials, including videos, that you produce. A mistake doesn’t disappear, although with time it can lose its impact.

This is why being accurate is more important than presentation, good English, or whatever. A mistake can cause untold damage more than the bad reputation you get from being labelled a write who doesn’t know how to write. It might be that you think the inaccuracy will become insignificant with the next release, and therefore it is better to concentrate on the English to the detriment of the technical side, but there are users of very old versions of software who search for answers on the internet because they haven’t got anywhere else to turn.

Remember you are a technical writer which means technical first and then writer and not the other way around. The writing side is important, don’t get me wrong, but it has to be technically accurate to pass muster.

And on a (very) final and sad note, Max Bygraves died soon after my post mentioning him. Even though my post had nothing to do with his demise, it does mean that his name will live on not just in the memories of old fogies like me, but by others who sees his name in “print” via this and the previous post and wonder who he was. His name has been committed to the ether one more time – never to be erased.

But it’s perfect!

It’s taken well over industry standard metrics to complete the procedure I was tasked with documenting, but it was worth it as the end result is something akin in the technical writing world to producing an award-winning version of a Shakespeare play at the Globe theatre.

I sit back and wait for the accolades from support to pour in. All those calls that can now be answered with a polite version of RTFM.

Nothing. Not a peep from support. Not the remotest hint that they even realise how much easier I have made their tawdry lives. I go home a little early that evening, a little despondent. But half-way home it dawns on me (as the sun sets), that our customer-base work in a different time zone and I can’t realistically expect any feedback until the middle of the night. My step is lighter as I arrive home, despondency a thing of the past, and the next morning I am up earlier than usual, all bright-eyed and bushy-tailed as I go in to work to receive the accolades obviously due me and by now obvious to one and all of my fellow employees.

I decide to pop in on support before making my morning cup of tea – so as to start the day with the blessings from support ringing in my ears. I enter and Bob (not his real name) looks up and smiles at me. Here it comes I think to myself. Bob, looks down at his desk for a moment and then back at me and says “Great, just the man I needed to see. You know that document you sent out yesterday, well we’ve had lots of feedback.” I can’t help puffing out my chest with pride as I wait for Bob to continue. And continue he does, “It is very confusing, it doesn’t describe the flow as used by our customers.” My chest goes from convex to concave in less time than it takes to actually exhale the necessary quantity of air for this to happen. “What exactly do you mean?” I whisper, backing (no longer strutting) towards the door.

Bob promised to send me the relevant emails and tapes of the recorded phone conversations, which would make the matter clear.

In my cubby hole (I’d grandly thought of calling it an office on my way in to work). I sat drinking my tea and wondering what could have gone wrong.

The emails and taped conversations arrive and I studiously go through them. Mostly the material consists of comments about the documentation being helpful and we need more of this sort of thing – the praise I had expected to hear. And then, I hear it. An irate customer complaining that the new document is confusing because it assumes two procedures, one after the other and not one large procedure. The customer concluded the conversation by stating it wasn’t clear the order to do the procedures and what would happen if you didn’t do both procedures but stopped at the end of the first procedure.

All the other users knew the system and didn’t have a problem with the two procedure documentation, sometimes only the first procedure is needed, sometimes only the second and sometimes both, one after the other. One user didn’t understand his own system and consequently wanted the documentation to describe his specific case of both procedures being needed, one directly after the other. Support spent time describing the flow for this one confused user and based their feedback on the time taken with this customer as a true reflection of the efficacy of the (my) documentation.

And from my perspective as the author? If nine out of ten readers are satisfied (even 99 out of 100) but one is not, then if the documentation can be modified so that the 99 are still happy and the one joins their ranks, this is the way to go. In this scenario, an extra line at the end of the first procedure specifying that in such-and-such circumstances go straight to the second procedure (without passing Go or collecting $200) answered the needs of the one without hindering the others in the slightest.

The reader is always right. Ensuring that the documentation satisfies this rightness is not always possible, since we write for the greater good of the greater number. However, don’t reject out-of-hand the critique of the lone voice – see if it can also be accommodated within the greater scheme of things without harming anyone else.

And this is the way to perfection.

And what about support?

I’m back from the summer break, and to quote Max Bygraves, “I wanna tell you a story”.

I have blathered on ad infinitum about documentation and training being two sides of the same coin. But, this fiscal simplification ignores the third leg, without which the chair will not stand up: Support. The written word passes on the information necessary in a dry, impersonal way. Training adds a little bit of humanity into the pot and some tips and tricks that are useful to know but somehow, for whatever reason, never get documented. And support is all human. You get to speak to someone who understands what you want and gives a reply to resolve whatever mind-numbing problem you were afflicted with.

Support use the documentation, and possibly the training, to pass this information across to the user. Often they know tips and tricks that they can pass to you to be included in the documentation and training materials. Support is the all important third leg in the transference of information!

And now to my story, which is about support, or the lack thereof.

Once upon a time, we were happily using HOT cable TV to supply all our recreational viewing needs. One day a wicked salesman from the competition, YES, knocked on our door and convinced us to switch to them. The channels on offer were, indeed in my not so humble opinion, better and the whole package, giving us more than we were getting, was also cheaper. Also, the salesman, always charming, said they would deal with leaving HOT, so we wouldn’t have to experience the unpleasantness of dealing with the HOT “stay with us” sales machine.

So far so good. The YES technicians came to install the various boxes for us and numerous children. Ah, but even at this early date problems started. We had asked for one thing and the technician wanted to install something else. We asked for one mega box (with VOD and recording and streaming), two semi-mega boxes (VOD) and two normal boxes. The technician had recorded all but one of the semi-mega boxes. A call to the ever-so-helpful salesman sorted that out (or so we thought). A misunderstanding and another semi-mega box was going to cost an extra $2.5 a month. What to do? We agreed. My step-daughter was present and signed the form that all was OK. Now my step-daughter, like everyone on this planet, is good at some things, brilliant at other things and lousy at still other things. In this case, she was lousy at verifying that everything was as it should be. The technician had recorded that we wanted four boxes so installed four boxes, even after we increased the number to five with the other ($2.5) semi-mega box. So now one child was left to suffer TV-less. We argued with YES and we talked to the salesman – but his job was done and after some meaningless promises to try and help, pulled out of the picture entirely, telling us that YES support was our only port of call.

We tried and tried with support but were constantly ignored or fed excuses (“but you signed that you were happy”, etc.) and told that to install the extra box was going to cost another $45. We could, if we wanted go for the ($2.5 per month) semi-mega box and only pay $20 installation. We decided to go for this option.

A digression: I received a bill from HOT for the month after we moved. I asked YES and they said it was because the bill was already in the works and it would be sorted out by HOT for the next month. I accepted this but when I received a bill from HOT for the next month, I phoned HOT support to ask what was going on. They were really nice on the phone and explained that they hadn’t received anything from YES and didn’t know anything about me quitting and to check with YES support what was going on. YES support told me I had to speak to HOT personally to disconnect, but they would refund the money paid to HOT (I am still waiting, but at least they are not totally denying responsibility for this).

And back to the main story. Another YES technician came to install the semi-mega box but told us it was a 2-man job and went away. A few days later a two-man team turned up and installed the box. And now the fun really starts. This team damaged a wall, broke the cable of an XBox (that was connected to the TV at the time they came) and did something to the XBox itself, probably dropped it on the floor, to make room for their elbows or something, so it also only works intermittently (which is slightly irrelevant, since the cable to the TV doesn’t work at all so we can’t see the extent of the XBox damage).

YES claimed that you can’t make an omelette without breaking eggs and the technicians had no choice. I claim that this is ridiculous and he should have fixed the wall and not broken the XBox in the first place. A few days later one of these technicians phones me to say he never touched the XBox or the wiring and caused no damage and wanted to come to see for himself. I suggested the next day, but he couldn’t come until three days later when he would phone me in the morning to arrange a time. Needless to say I am still waiting for the phone call (many days later).

And the semi-mega box? Well it only worked like a regular box. We phoned YES support and they told us to phone a different department (no possibility to transfer the call). Then we are told it is not that department but the people we phoned in the first place. Back to them and they ask a few questions, mainly centering around a router and whether it was plugged in or not. We didn’t have the router, so no wonder the semi-mega bit didn’t work! (Actually the technician who originally installed this box mentioned that the TV couldn’t handle the extra – but he never told us at the time, nor YES, who still claim their pound of flesh for a service apparently we could not receive).

Another technician came knocking on our door (without the 15 minute warning to get back from my workplace, that YES support had promised me). This technician looked at the connection and said it would need replacing since it was badly fitted, able to disconnect at any moment. Within 30 minutes, Edi (named because he deserves the praise, being the only one from a large team we have now met or talked to, who actually has done a good job) had the router in place, redid the connections and checked that the semi-mega box actually worked as it should.

So where does this leave us?

• Owed money for two-plus months paid to Hot that we shouldn’t have paid.
• Owed money for a time when the semi-mega box acted as if it was a normal box – because there was no router.
• Requiring a wall to be fixed.
• Requiring a new XBox cable and possibly XBox itself (or checkup with a licensed XBox repair station).

Support is important. It is the third leg, without which the whole edifice topples over. YES have a deal that if you are not satisfied with them you can get your money back. Unfortunately we are not part of this deal. HOT might not have the better channels, but they have by far the better support. And that is worth every channel in the world.

So what are we going to do? Give YES one last chance to make good, and if they don’t, go to court for damages and then go back to HOT.

Addendum: Yesterday I had a call from YES asking if I was with HOT or YES. I replied that unfortunately I was with YES but because of the disastrous service was thinking seriously of the upheaval of returning to HOT. His reaction? He put the phone down on me!

The page versus the slide

What differentiates the page from the slide, the PDF from the presentation, documentation from training?

Forget, for the moment, documentation via videos and the like, what I want to do here is look at traditional documentation, the written word, versus traditional frontal training and try and identify the overlap between the two. many times I have argued that documentation and training are two sides of the same coin, that training is just another way of presenting material that is otherwise covered in the documentation, and thus documentation teams and training teams should be grouped under the same organizational umbrella.

I know that this is not 100% true, since in training there are always the little tips and tricks, that in the end can make or break the user experience, which nevertheless, for a plethora of reasons never make it into the documentation. But there are solutions to this as well without resorting to a week at a course somewhere exotic, like forums where users get to share their experiences (for good and bad).

Where do we go from here?

More and more we hear about the death of the PDF. More and more we hear that the written page is out.

Kindles and other similar devices now replace the old paper format that the previous generations grew up on. The iPad, which is becoming the generic name for any tablet, is fast becoming is the major device used for accessing the internet (catching up with the smartphone, both of which leave the PC and laptop way behind).

Where does that leave us, technical communicators who spend a large part of each working day doing the modern equivalent of putting pen to paper, by putting finger to keyboard (it really doesn’t have the same ring about it).

So, the written page is on the way out? Actually, personally I don’t think so, but to know why you have to read on!

Why technical writing is not boring…

Sometimes forums contain useful information, sometimes not. Every once in a blue moon they contain a gem. One such jewel in the rough had the title “Advantages of Being a Technical Writer” and the content for discussion was the following pithy statement:

Technical writing is not as boring as it seems. There are a lot more advantages to being a technical writer than people realise.

This reminds me of the Monty Python article about accountancy in the Big Red Book. Nineteen pages of drivel cut to one page of tedium. But the author thought he was being interesting and I daresay clever with it.

I would hazard a guess that there isn’t even one single profession (including the oldest one) that is 100% interesting 100% of the time. But what makes a job interesting is not so much the job as how you look at it. I know that I couldn’t be a fireman, so if this was my dream job I would have ended up bored, sitting behind a desk working on the administrative side of the profession instead of sliding down a pole at the drop of a hat. If you like your job, then the interesting bits are more interesting than for those that don’t like their job. So to start a discussion like the above, implies that the author is trying to come up with reasons for something he doesn’t want to be.

<sidebar>
And while ranting about this, amongst my other bugbears (like the demise of words like amongst and whilst from popular English usage), I will take this opportunity to apologise to Mr. Orwell for daring to compare myself and my wannabe ramblings with his literary genius in my last post. Some, thought it presumptuous of me, as indeed it was.
</sidebar>

A quick search of the web turns up a few articles about the advantages of being a technical writer, none of which, at least after a cursory glance, started by stating that the profession is not as boring as it seems. A search for technical writing as a boring profession also turns up quite a few hits, but the few I checked out explain why it might not be what you dream about becoming when a child but still makes for a reasonably satisfactory career choice.

I have yet to find a such a negative opening line to a reasonable title (“Advantages of Being a Technical Writer”).

Of course there are advantages to technical writing as a job and of course it is sometimes boring (try sitting in a technical spec meeting that lasts for two hours with each developer explaining the finer points of his algorithm to resolve whatever issue the spec is coming to resolve without nodding off).

<sidebar>
Curl your toes up in your shoes to avoid falling asleep in these meetings and thereby embarrassing yourself unduly.
</sidebar>

After more than twenty years trying to be a technical writer I can categorically state that it is not boring – it is just me that sometimes is.

Who has the right to make the rules?

A while back, in a post where I discussed the agile methodology (It pays to be agile) I quoted one of George Orwell’s rules, “If it is possible to cut a word out, always cut it out.” and then proceeded to show how even this rule was too verbose.

Georgy Boy had more than this one rule in his arsenal and a whole treatise ) that discusses them.

Way back when I started this blog, I enumerated my ten commandments – so let’s see how what I think is the right way for technical writers to write stands up against the great Orwellian writing rules.

George rule number one: Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
My rule number 9: Don’t use buzzwords. Our reasoning behind what are similar rules are different, but the fact remains – to quote from the Orwell treatise: Common phrases have become so comfortable that they create no emotional response. And in technical writing terms this means that the buzzword detracts from what you want to say, adding nothing of value.

George rule number two: Never use a long word where a short one will do.
My rule number 4: Keep it simple, keep it short. Many of my posts have advocated minimalistic documentation – say what needs to be said as succinctly as possible. The less the merrier.

George rule number three: If it is possible to cut a word out, always cut it out. Great literature is simply language charged with meaning to the utmost possible degree (Ezra Pound). Accordingly, any words that don’t contribute meaning to a passage dilute its power. Less is always better. Always.
My rule number 4: See above.

George rule number four: Never use the passive where you can use the active.
My rules: More a technical writing rule than one of my ten. Actually, I disagree with this rule for technical writing as well. I prefer to be active when referring to the user and passive when referring to the software. Thus, click xyz to do something. And then on a new line, again to differentiate what the user actively does to the response by the system: The something happens (now is not the place to discuss the age-old discussion about the merits of displayed versus appears, etc.).

George rule number five: Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
My rule number 9: Buzzwords rear their ugly heads again.

George rule number six (out of five): Break any of these rules sooner than saying anything outright barbarous. This bonus rule is a catch-all. Above all, be sure to use common sense.
My rule number 11: Break any of these rules whenever necessary.

My other rules are aimed at technical writers and not nobel laureates. But I am sure Mr. Orwell would agree that keeping the reader in mind, keeping the material focused, and checking what you write are also valid rules.

And since I am making these rules – I don’t mind be a few days later than I said I’d be. Rules are, after all, made to be broken.

The great English hanky

I am English.

So what, I hear you mutter. So what that you like cricket and have an affinity for whisky (as opposed to whiskey). I can cope with that.

But when mentally ticking off the idiosyncracies of the typical Englishman (which I am not) you forgot to mention the hanky. That piece of material stuffed in the pocket full of old nose effluvia, and required for the storage of future nasal effluence.

Ah, I sense you mutter, disgusting!

Disgusting it may be, but useful when you sneeze and end up with a nose that resembles Victoria Falls (to remain with the English theme), and nary a tissue in site.

Documentation is sought of, in a very vague and ethereal way, similar to the hanky. Not everyone’s cup of tea (milk, no sugar, please) but of need to some. Most can, and do, happily survive without one, but when something unexpected happens they normally access the nearest support center (akin to the tissue). But what do they do when it is out of hours and support is not available? For the Englishman this is not a problem. He reaches into his pocket and extracts the rag known fondly as the hanky (akin, in this metaphor to the documentation).

Some read most of the documentation. Most read some of the documentation but all want to know it is there. Just like the hanky, it is reassuring to know that you have something that is available in your hour of direst need.

This post should never have happened, since it breaks my rule about posting every two weeks. So please ignore it and return next week when I’ll discuss rules, their usage and the breaking of them thereof, in more detail.