Calling Your ISP

This post has nothing to do with technical writing. I apologize to all who expected me to stay on topic.

I saw over on TechBlog that a number of people, having trouble with their DSL or cable ISP, were calling in to complain. One person had a perceptive comment:

I have found that the only way to get Comcast, & Warner before them, to respond is to hit them in the pocketbook.

The last time I had a multi-day intermittent outage I began calling and requesting a service call EVERY TIME I got a blip in the service. I would have them come out even if I had service back when the service guy called me to confirm.

I patiently reminded everyone I talked to that I was going to have them paying people to come out so much they would not make a dime off my service (TV and Internet) until they got it fixed for real.

While I think they've got it basically right, they've got the wrong approach. You do need to call, and politely and insistently remind them you've paid for this service and you need it to work without glitches. But you shouldn't view it as pocketbook retribution. I'll explain.

Have any of you worked in a call center?

If truth be told, in technology, many of us would raise our hands. It's where you start out. It's where you're glad to get the heck away from. It's painful, ugly and often sad.

Call center employees are viewed by their employers as moronic wage-slaves who need to be managed every second or they'll start screwing around, wasting time, stealing things and probably running riot. They know they underpay you. They know the job is terrible and turnover is high. They also know there's just about no fix for that. Very few people like working in a call center, unless the options are so bad that hell-1 is a good choice.

Companies lose profit every time you pick up the phone. It's one reason they pay technical writers, because even if you pay $100,000 for a manual, if it results in 20,000 fewer calls to the service desk, it may well have paid for itself. The costs are massive. Each employee requires another in administration. There are salaries to be paid, equipment costs, phone line costs and high management costs, because you have to bribe managers with filthy lucre to work in call centers. Each call costs something like $40 after all that mess is calculated. So companies try to reduce costs any way they can.

The first is by underpaying people, knowing that everyone needs early job experience, and then by having a set of really restrictive rules to keep them in line. You need to be on the phone all but three minutes a day. You can only keep customers on hold for so long. You have to follow scripts. It's a lot of rules, and most people screw it up, so they hold the threat of having a negative recomendation over their heads. If they could, they'd have Roman centurions in there drumming a beat on the slave drums and chanting "Row" in unison. It is that bad.

When you call Comcast or another ISP, you will spent your first few calls dealing with these people, who have almost no power. They can go through the script, put in the notes column that it did not work, and then ask a supervisor to look at it. That supervisor spends her whole eight-hour shift solving problems that come up time and again. If given a chance, that supervisor will ignore the account. There are other fires to put out.

There's one exception.

At the end of the week, they run status reports on all their calls, and the machines churn out reports that tell them, among many other things, how many repeat calls occurred. Smart managers hate repeat calls.

Repeat calls means total defeat on all fronts. The customer is calling back, taking up resources, and costing money -- remember, at $40 a call, five calls means you've probably obliterated their profit on you for that year. The customer is not getting the right answer, so they are not happy, which means they will defect if a competing option comes close enough. And finally, last but not least, call center employees are starting to take one look at the notes by the customer's name, realizing that they the employees will get dinged for not solving this one, and they're transferring the call or dropping the call or doing anything but solving it.

Everyone gets screwed, and the customer goes home unhappy.

When they see outstanding issues that are costing them that much money, they act. It doesn't matter how loud you shout, because being on that repeat call list is what gets them to pay attention. There's no point being mean. If you're an angry jerk, all that happens is that the employee you talked to gets drunk and goes home and beats his kids, but the managers never see it unless you're so angry they intervene and cut you off. If you're polite, calm and call back many times, they eventually take one look at the cost and say, "Holy mother of God, let's get the right resources on this problem before we lose more money on this one! It's a turd on fire! Get it out of here!"

It will take a lot of your time. You will call up, listen to the Muzak Electric Strings cover old Beatles and Metallica songs, suffer through the initial "script" they have to read to make sure your appliance is plugged in, you're not insane, the machine is turned on, you're in the right city, and so on. But after you do this a few times, you're going to be at the top of those problem reports, and you will get taken care of if there's a fix at all.

The Universal Document

This weekend I stayed with a friend of mine, who is a project manager but also writes procedural documentation for his employer. We were kicking around some ideas over a couple root beers on the back porch. He advanced the radical thought that the longer a documentation project is worked, the closer its writers will come to a "universal document," which is an archetype of how all documents can and maybe should be listed. On the back of an old envelope, we came up with the following:

I. Introduction

1. Thematic - introduction to the topic, description of its major parts, its function and general theory.


2. About this document - how it is written, conventions used in it, who wrote it, why it's important, where to buy the latest version.


3. Revision History - editions and edits of this document.


4. Copyright - who owns it, what their rights are, who can read it, what their rights are.


5. Resources - more information about the topic, the document, or the authors

II. Sample Chapter

1. Self-reflexive definition - refers to I(1), and the place of the topic of this chapter in a general theory.


2. Categorical vocabulary - how to understand this topic.


3. Walk-through - outline of basic use case.


4. Summary material - seal together theory and details.

III. Appendices

1. Glossary - terms used.


2. Bibliography - resources used.


3. Contacts - people responsible.


4. Legal - laws and regulations to which it complies.

In all probability, I missed a few, especially on this shaky and rainy Monday morning. It's an interesting idea that a universal template could exist, and then we could use that standardization for computer-based parsing or search guessing (look in the middle of Sample Chapter for vocabulary, toward the end for technical detail).

Assuming guaranteed readership

One thing that I return to time and again when explaining technical writing to potential employers is the dangerous concept that people do not sit down and read manuals, for the most part.

They pick them up in odd moments, they skim them, they read the table of contents and pick a juicy sounding section they hope will be a tool from which they can leverage all other knowledge. That's the ones who are lucky enough to read before starting a project.

The majority use software the way playful simians have adopted tools since the creation of the infraorder. We pick up the new gadget, try a few things, talk to other people about it, and try to get some sense of a singular principle which explains how it works. We play with it. When we get stuck, with the boss yelling down our shirts, we dash for the manual and look up a likely keyword or two.

As technical writers, we need to be aware that most of what we do fits this use case. The nervous, harried, disinterested reader. When we write documentation, we cannot assume that people are reading it linearly, or that they're interested in reading a lot of words. Their goal is to read as little as possible, and to work from big concept down to details.

In this time of buzzwords like DITA, single-sourcing, portability, usability and others, we often forget the age-old skill of telling the tale in as few words as possible. Each time a non-technical member of my family buys a new phone or camera, and the 200 page manual sits on a shelf while they remain ignorant of how to do basic tasks on the gadget, I sigh and remind myself of the need to write with brevity.

Manually merged WebWorks help systems

If you already have several help systems generated, and don't have the source files, but want them to act as one help system with table of contents, index and search index intact, you must merge the help systems manually.

Manually Merged Help on WebWorks ePublisher Pro is a good walk-through for this gnarly process with WebWorks ePublisher Pro 9.2 and WebWorks Help 5.0.

Knol: A way to make better search results

Homeboy Chris Blanc has an interesting, in-depth post concerning Google's Knol, which was announced earlier this week:

When they wanted to take out Microsoft Internet Explorer, they pumped money and developers into Mozilla Firefox, making it as corporate of a project as IE. Result? Many people use it, believing it to be a real alternative, while Google slowly slackens its support into the background.

Finally, Wikipedia: Google needed a way to provide some kind of standard result for any search query, because too many people were spamming. So they encouraged wikipedia, knowing that its content would eventually get out of hand.

Now, they’ve introduced Google Knol, which is a wikipedia clone — except that it’s hybridized with a group blog, and is only open to select contributors. Thinking of Associated Content or Reddit? Yeah, me too.

It’s a good way of acknowledging what Wikipedia tries desperately not to let the world know. Most wikipedia articles are written by relatively few people, maybe 2% of the contributing audience. They are augmented by another 10%-20% of the people there. The rest of the people on Wikipedia perform really obvious monkey tasks like plagiarizing websites that are expert in their area, so the Wikipedia page appears above them in search results. This was basically a giant web real estate grab.

With Knol, Google is starting where Wikipedia left off.

While I think this view is correct, I think we should also consider that Knol is part of an ongoing attempt by Google to control the information going through their search engines. Since last month's massive spam attack, Google has been publically wary of a problem they've known about for some time.

The Bi-Axial Dilemma in Document Organization

I'm sure most of you will dispatch this topic with a bemused "Sounds just fascinating," but it is of note to those of us who write docs for a living. The rest of you just hum Radiohead songs for a few minutes, as this won't take long.

When you are represented data of two axes in a document, your most pressing question is which axis to make primary, which ensures that the secondary axis will be repeated as secondary organization at each stage of the primary. For example, using CNN's privacy policy, we have two axes:

AXIS ONE

The Information We Collect
How We Use the Information
Cookies & Web Beacons
Collection of Information by Third-Party Sites, Ad Servers, and Sponsors
Our Commitment to Security
How You can Access or Correct Information
Special Note for Parents
How to Contact Us
Updates & Effective Date

AXIS TWO

Internal Use of Information
Use of Information with Business Partners
Personally-Identifiable Information
Statistical Information

These are not the axes as we'd represent them in a design document, but how they've shown up in the document. We might describe the first as topics regarding personal information, and the second as areas of use, although axis one has been stylized to be more a linear discussion of the use of personal information.

This gives us two options:

OPTION A

1. The Information We Collect
1.1 Internal Use of Information
1.2 Use of Information with Business Partners
1.3 Personally-Identifiable Information
1.4 Statistical Information

OPTION B

1. Internal Use of Information
1.1 What is collected
1.2 How is it used
1.3 Methods of collection
1.4 Security

Of course, Option A is the one chosen by CNN. I find it useful in these situations to go with a general rule: which axis would, if repeated, cause the most tedium. It is often but not always the one with more items. In the case of end-user docs, we correlate steps of learning to a task and use that as the primary axis. It's an interesting study on a Thursday otherwise full of scripts and server configurations.

Case Study: ZDnet blogs

I'm not a Mac fanboy, but I think the principle of the Macintosh was actually one established years earlier by the Commodore 64 and the Apple ][ series of computers: interface counts.

The technical performance is only half of the equation because the user is essential, and the more "familiar" the tool is, with fewer weird surprises and relatively intuitive function once they understand its basic principles, the more they like it. Every piece of technology needs a functional, conventional, logical interface.

I am routinely amazed at how much this is ignored.

Today's example comes from ZDnet blogs and their very, very broken comment system. It's both odd this is broken, because comment systems are now very mundane, and very predictable, because most web sites have at least one gaping break of the following varieties:

Security hole. Your PHP page is an SQL injection waiting to happen.

Broken scripts or missing essential pages. No one really crawls their own sites.

Broken interface. This is most common. In the rush to get a project done, people forget to check whether the normal user can navigate it.

Strategy failure. Many web sites, in a zeal to gain more market share, provide a lot of what their users don't need, and very little of what their users have proven to want.

ZDnet committed the following gross errors:

On a post, they provide a comment blank, but no indication near it of whether or not the user is logged in or could log in, leading most to assume they are logged in. Why? Every site requires its own login, so we're used to finding sites to which our cookie is the key.

When you do enter a post, presumably something you deliberately want to say and spend time on, and click enter, it takes you to a user registration screen -- thanks to the no cache pragma on the previous page, forgetting everything you entered. This is a big no-no for retaining users.

When you do sign up, if there's an error in your submission, it automatically rechecks the boxes that sign you up for its mailing lists. If you uncheck them, no luck: the system automatically signs you up for its two basic mailing lists regardless of what you entered.

At the point, five or six screens in, when you're done with this whole mess, you get taken to... a generic introduction page. The original page you're reading? You have to find it elsewhere.

This is just another example of how big media is following the print media model. They assume that if you get to their publication, you'll think how great it is and just start reading any old stuff on the page. What they forget is that the web is not a 3D medium, but a 4D medium, with topic being that fourth dimension. If we didn't come in the front door, we came in looking for something.

I think it's bad interface for a writer to waste time on shock and horror at the incompetence of someone who should know better, and as a consultant, I'm too aware of how many companies screw this up. Let's just say that a well-done site is the exception not the rule, and you can apply that homily to documentation, code, project management or advertising if you'd like and be equally correct.

It may be time to resurrect the "webmaster" role, so to create one person with the power, authority and responsibility to fix everything on a web site, or harass those who are holding up the process (legal teams and marketing, I'm looking at you). If I feel like navigating this mess again, I might mail ZDnet. Or not.