User Advocacy

Calling Your ISP

2008-04-07T13:54:00.000-07:00

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

2008-03-31T13:50:00.000-07:00

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

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

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

Revision History - editions and edits of this document.

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

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

II. Sample Chapter

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

Categorical vocabulary - how to understand this topic.

Walk-through - outline of basic use case.

Summary material - seal together theory and details.

III. Appendices

Glossary - terms used.

Bibliography - resources used.

Contacts - people responsible.

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

2008-02-20T15:53:00.000-08:00

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

2008-02-20T15:31:00.000-08:00

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

2007-12-17T10:56:00.000-08:00

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

2007-12-13T12:45:00.000-08:00

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

2007-12-13T09:38:00.001-08:00

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.

Mailing lists: why so difficult?

2007-12-11T08:48:00.000-08:00

I have argued, literally for years, that web applications need to fit into some common modular framework so we can get them to interact. People around me were too busy seeking personal glory by creating and maintaining proprietary solutions, and what gets forgotten is the end user, which in this case is the average person trying to use that website and not waste even minutes on broken interfaces.

Minutes add up, after all, but even more importantly, the stress level rises each time we encounter something busted especially if there's no good reason for it to be broken.

This week, I decided to drop a number of mailing list subscriptions to digest format. Digest format is easier for me to read, since it compiles all messages into a single email, and encourages me to carefully pick which discussions into which to jump. Some of these mailing lists I really want to be able to read, but it's generally for the 5% of the people who routinely have intuitive comments. Putting the list output into a digest saves me from filtering through hundreds of emails that are often the content equivalent of "me, too!"

Putting together a mailing list is not a hard task but not a simple one either. You need some kind of interface. You need a database or other storage method for records of who's subscribed, and to keep archives. Finally, you need something which can interface with the mail system on your web host, so it can send out mail messages and receive messages to send back out to the list.

Of the dozen mailing lists I'm on, I wanted to convert the seven top lists by traffic from individual messages to digest. The results revealed just how often this basic, simple need is broken. Here's the breakdown:

Two lists worked perfectly. Both of them used the mailman software's default interface and did not make it interact with their other web applications. As a result, each site had a wiki which required a separate login, a blog which required a separate login, and so on.

One high-traffic list had a well-integrated interface that was immersed in a bafflingly complex site design. What's so hard about making one place where you change all your user settings? It's no different programmatically, but requires more organized programmers. It took several tries to get this list into digest format.

Three sites were varying degrees of disaster. Three gave adequate interfaces that didn't work, so that when I changed my settings, I got a 500 broken script error, a pipe broken error from their web objects framework, or an input-not-expected prompt. These looked to me like interfaces that once worked, until the site moved from one ISP to another or had more stuff installed.

The final site was completely broken, and ironically, it was a site for interaction designers that normally does a good job of making things work intuitively. The member interface was easy to find, and I really like their verification system, which sends you an email and requires a response to set a cookie - no passwords! But, the outbound email wasn't working for the first two weeks, and then, when it was and I could log in, the "edit member profile" option on the web page returned a javascript error. I ended up unsubscribing, and if I remember, I'll resubscribe when they've had time to fix things.

All in all, this reminded me of something I've noted since 1993 about web sites. They are organic entities, but their parts are not alive unless someone is focused on them. On a user-edited site like a Wiki, changes can be made, but this results in conflicts between overall vision and the abilities of individuals. On most web sites, however, this means that notice has to work its way up a chain of command.

This chain of command is most often balkanized. Developers are exhausted with requests for features from management, management is trying to keep user interaction specialists at bay, user interaction people are trying to introduce simplifications which require features from management, and so on. Someone in some role is needed to bring it all together, and this requires the energy to break these silo boundaries, which often doesn't happen for someone already burdened with translating content into an acceptable form, and then a web-acceptable one.

What I fear is that the end result is that users are becoming accustomed to broken pages. They have a predictable response, which is to click elsewhere, and ignore the error and possibly the site. It's as if you went to your favorite restaurant, and went into the bathroom to find water all over the floor. Suddenly the waiters look careless, and you see details you might normally miss, like dust on a counter or dried pasta sauce on the floor. Your stomach says eat elsewhere.

Web users do the same thing. Maybe it's time we all consider the users, and start standardizing interfaces and the hooks they use to communicate with each other, so we can avoid this fiasco in its many forms in the future.

Technical Writing in Transition - Part V

2007-11-20T14:07:00.001-08:00

The best technical writers I know are the ones who happily roll up their sleeves to dive into an unknown situation and get dirty. They are word warriors with the goal of saving that user who at midnight, with something done by dawn, needs to read one paragraph, understand it and move on so she can return home to her family. These technical writers are commandos in planes far above the earth, grabbing their laptops and chutes and leaping out the roaring open door.

This aspect of technical writing will never change. To enjoy confronting the baffling, making it clear, and teaching it to others is the eternal personality type of the person who will become a technical writer. Where this will change, in our new user advocate sense, is that we will do so over the life of the product and will channel information in both directions.

The flip side of this change is that we can also become a part of the development team that ensures the interface is consistent, the application works from a user's point of view, all of its parts work correctly and the experience confronting the user is one they will want to return to. We will be instrumental in communicating application to user, and user to application. This is an indispensible, professional role, while showing up to WTFM on contract no longer is.

Support for this idea has come from those trying to make development more efficient. Steve McConnell (author of Code Complete) proposes early draft user guides as a replacement for requirements specifications. Many startups use writers from inception to document internal methods and procedures, and in the process have employed them as software testers, quality analysts and even interaction designers because of their dual specializations as experts in the software and advocates for its users.

The future for technical writing may be bright, and also dark, as any transitional time must be. We have to let go of the old, and make a big push to accept the new, and then we will find ourselves in a better place. When we do this, we will be able to fit into the future needs of our industry and market ourselves more effectively, creating a longer-term role for our profession.

Technical Writing in Transition - Part IV

2007-11-20T14:06:00.000-08:00

Our future is cheap information. Already the internet is awash in blogs, newspapers, forums, mailing lists and other forms of information. Where when technical writing began information was scarce, the question now is how to filter valuable information from the flood. The killer app of the last decade has been the search engine, but the weakness of search engines is that they cannot separate the relevant from the irrelevant based on complex criteria. For now, it takes a human to do that.

Documentation has become omnipresent but universally criticized because most of it is not helpful. One reason for this is that the technical writer usually has minimal input back up the chain of command, so when they encounter something unexplainable or illogical, there is no recourse but to document vaguely. Even more, since the WTFM mentality encourages employers to pick up a technical writer at the end of the project only, most technical writers find themselves sitting down for two weeks with a product before they have to start making reams of text, and quality is affected.

In the cheap information future, that kind of documentation is less worthwhile. The generally bad quality of documentation which came with software in the 1980s and 1990s spurred a huge market in "best practices" books, most notably from O'Reilly and Associates, which described not only how to use an application but how to use it well. They gave more information than manufacturers would by assuming users would be more aggressively seek power users tasks, and that teaching all users best practices would not leave any in the dark.

To compete in a future of cheap information, we need to change our role in two major ways:

1. Best Practices. We must champion "best practices" user-computer interaction by emphasizing the most powerful, not simplest yet leaves out details, way to do a task.
2. User Advocacy. As part of our "two way" communication between user and product design, we must not only explain product to the user, but explain user to the product and the team that makes it.

Every software product lies between two points: the people using it, and the goal of using it. A word processor exists to get its target audience to be able to accomplish a range of tasks without significant confusion and frustration. Not surprisingly, word processors come in different flavors for different levels of experience and specialization.

User advocates want to simplify and make more effective every product we touch, and produce simpler and more effective documentation for it. Our goal is to destroy confusion and ambiguity. We're also UI creators, but too ofen, UI design is contingent upon quality product design -- if the product is coded around the wrong processes for its intended use, or its design is ignorant of common methods, it will be awkward to use in the way it is most commonly used.

In this new role, we'd be part journalist, part communicator, part trainer, part project manager, and part interaction designer and user advocate. This is to the benefit of writers, as we get to spend the entire product development cycle getting to know it and get a more justifiably necessary and lasting role, and companies, as they get several roles in one.

Technical Writing in Transition - Part III

2007-11-20T14:05:00.000-08:00

Opportunity for future technical writing exists in the dual role of technical writers. We unlike every other role both understand the product, and see it exclusively from the point of view of a user. The shifting market has provided room for this skill to add value not just to the product, but to the company that produces it.

Technical writers do not produce income-generating products. We reduce costs by eliminating confusion that would otherwise be kicked along the line to the technical support personnel, and we increase brand strength by making customers more satisfied with their product purchase. On the year-end assessment, there is no way to prove technical writer return on investment. Over the lifespan of a customer however we build loyalty and increase profit margins.

For most users, technical writing is the first point of contact they have with a product and the experience that defines their perception of the company that made it. After they unwrap the software or hardware and start playing, their first question or doubt will send them to the manual or online help. This first impression of "brand identity" defines what they perceive about the company, how well-organized it is, and how committed it is to its customers.

A manual or help system that communicates quickly without leaving out vital contextual information, which saves time when problems arise, makes a good initial impression that lasts for the life of the product. Similarly, a product with a quality visual design communicates organization and competence. As the example of Apple computer shows, making products look good, with clean interfaces and quality documentation, creates an initial impression that allows users to overlook other shortcomings later in product life.

For more companies to gain this brand identity, without having to hire a small army of other people, technical writers can be the deciding factor. Since unlike all other roles in production, technical writers think about the product exclusively from a user-centered perspective, we explain it in the language of the user, and apply our knowledge of user psychology to break down raw information and introduce it in the right order to be understood.

In production, roles define focus. Programmers concentrate on making the machine produce predictable results. Project managers try to keep the team organized and on schedule. Artists create visuals. Interaction designers script interfaces and study user response. However, there is no role which from product design to completion remains focused on how the users make the technology work to accomplish tasks, except the technical writer, by the nature of our need to explain the product in those terms.

Here is an unrealized opportunity. We can WTFM and remain in a silo called "technical writing" while growing rapidly less relevant, or we can take on an additional role and make ourselves vital. We would be moving from "one way" thinking of explaining technology to users, to a "two way" view in which we both explain technology to users and explain users to technology. This would make products appear more organized, and raise brand value.

Technical Writing in Transition - Part II

2007-11-20T14:04:00.000-08:00

What characterized technical writing during the early digital years was what we might call a WTFM mentality, for "write the fantastic manual" (or words to that effect). When software or hardware development was done, the tech writer came in on contract and produced a manual, then vanished from the process except for occasional updates. The task was to produce the manual as the last task before shipping.

With the change in our society brought by digital technology has come a change in what the fantastic manual might be, both in form and content. In the 1930s, an egg-beater was a separate tool from a mixer; in the 1950s, they were interchangeable attachments to a motorized mixer base; in the 2000s, they are different rotation patterns programmed into a mixing unit which hooks up to the network, serves a web page of usage statistics, and probably stores recipes to boot.

The way our users read documentation has changed as well. People now are as likely to read the manual on a computer as on paper; in the future, they will be reading it on phones, video screens, e-ink tablets or have it scroll across their forearms in LCD tattoos. Since they know the basics of our networked gadget world, they are less likely to read the manual linearly, and even when not in a hurry they start by looking up terms, skip chapters, and skim.

Technical writing has adapted with three fundamental changes:

1. Task-oriented writing. Instead of describing the parts of a system, we walk the user through tasks and explain technical knowledge incidentally.
2. Single-sourcing. Write-once, read many; we write in small blobs which can be reorganized for online help, web help, printed manuals or marketing.
3. Plain English/Simplified text. We describe the interface, not theory, using code-like patterns of if-then language and action sequences.

The first launches users into a technology by giving them a basic task and building on that knowledge. The second breaks writing down into interchangeable blobs, like note cards, that can show up in manuals, online help, marketing and web site FAQs. It granularizes writing and makes it easier for a user looking up concepts in an index to understand them, but removes much of the emphasis on text flow.

The third simplifies writing into formulaic, code-like language which emphasizes parallelism between different tasks. The first attempt to achieve this, Plain Language, distills the host language into a few thousand words and a few hundred phrases so readers can easily spot parallels between similar actions. The second attempt, Structured Language, rigidly scripts procedures in a logical format that resembles computer code. Although neither has caught on broadly, elements of both have now been integrated into technical writing as practiced at the cutting edge of the industry.

These modifications to the skill of technical writing since 1987 or so have not changed the basic attitude of the WTFM mentality. Instead, they have prolonged its life by upgrading WTFM instead of changing course. However, to a public increasingly acquainted with the similarities between computer-based tasks, WTFM does not provide the depth of information they need, so instead they buy third-party "power user" books to fill that need.

The profession is slow to change. Beyond inertia, technical writers have bumped themselves up to a "professional" salary over the past four decades by WTFMing quickly and frequently. If you want to make it big as a technical writer, the theory as popularized in books like "Making Money in Technical Writing" by Peter Kent goes, become a contractor and rush like a fiend to write as many fantastic manuals as you can in a year.

In the past, that approach worked because much of the manual comprised general introduction or loosely-concealed translation of engineer notes. Changing market information suggests that trend has run its course. When the basics of technology are known, it is easier and cheaper to have an engineer type up notes and hire a college student to format them. As we have made writing more accessible, we as technical writers have become less essential.

Technical Writing in Transition - Part I

2007-11-20T14:02:00.000-08:00

Summary: Once a necessary part of product deployment, technical writing is slipping to an afterthought. Why that's happening, and how to re-define technical writing to both overcome it and deliver better value, by experienced technical writer, developer and project manager Chris Borokowski.

A human being should be able to change a diaper, plan an invasion, butcher a hog, conn a ship, design a building, write a sonnet, balance accounts, build a wall, set a bone, comfort the dying, take orders, give orders, cooperate, act alone, solve equations, analyze a new problem, pitch manure, program a computer, cook a tasty meal, fight efficiently, die gallantly. Specialization is for insects.
-Robert A. Heinlein

Among technical writers, the state of the profession is a form of contention in itself. Many argue that assuming change is afoot is to knuckle under to the steady stream of buzzwords and fads that make a few venture capitalists rich while everyone else hits the job boards again. A growing faction of otherwise sceptical writers are thinking instead that transition is upon us, and will reward those who adapt.

To understand this change, we need to track the development of technical writing.

Originally a bizarre hybrid between psychologist, journalist, and instructor, the technical writer compiled scattered notes written by engineers and converted them into manuals that normal people could read and understand. This allowed the product-buying public to use technology with which they had no familiarity.

Technical writing through the 1950s and 1960s followed this pattern. Users were expected to have a high school education including some math and science, so much of the job involved explaining specifics in terms of the general skills with which users were more familiar. Gadgets varied widely and so the writer served an essential role, translating engineer complexity into end-user clarity.

With the transistor revolution of the 1970s, two crucial changes occurred. First, the computer migrated from the machine room to the desktop. Second, high schools got more lenient at the same time users became more acquainted with television media. This new generation were shaped by seeing machines used before understanding the principles behind them, which laid the ground for the interface revolution to follow.

On the heels of those developments, a second computing revolution occurred in the late 1980s and early 1990s. Both the graphical user interface (GUI)-based operating system and the world wide web took existing technologies and put them to new use. This usage redefined the comput from being being a calculating machine to an information browser. This role shift entailed thinking about interface in user-centric contexts and resulted in both these revolutions.

Usage exploded since the layperson could now interact with a computer as they would a video game, vending machine or automated teller. This in turn spurred a network revolution. Since the computer was viewed as an information browser, it needed connections to information, so the network became the computer. These influences caused the computer to become increasingly powerful, standardized and ubiquitous.

The standardization affected technical writing. Digital technology exists within an environment designed by the machine, and it makes sense to have single pieces of software handle functions so commonplace they should be standard. This means that, unlike physical technologies, digital machines have a language of interaction which makes most tasks similar in the actions they have in common.

Newer generations of users come to expect this standardized language, and that they can pick up a video game, computer program or phone and figure out the basics of its function with a few minutes of play. They may not have the background in physics, math and electronics that previous generations took for granted, but they do not need people to explain standard interfaces.

Now that the internet age has boomed and rebirthed itself, technical writing struggles to adopt this new role. Complexity has increased, but so has standardization, which means the userbase is well-informed about generalities but not specifics. As the audience has more tasks of a diverse nature, thanks to this efficiency boom, they expect specific knowledge distilled into digestible fragments for quick use. The job of the technical writer is as a result growing and shrinking at the same time.

Slashdot 10th Anniversary Party in Houston

2007-10-31T10:23:00.000-07:00

When I volunteered to sponsor the Houston Slashdot 10 Year Anniversary Meetup, I had no idea what to expect. These are the people who will tear up a message board with hi-tech information and then devolve into a fit of giggles and "In Soviet Russia, disk drive formats you!" refrains.

We converged on Agora in the Montrose district. It's a quiet coffee house that also has some quality beers and occasionally, tasty junk food. Other than intoxicants and junk food, I can't think of a thing nerds require besides Wi-Fi, and at least one participant reported that it was working quite well.

Of the 57 people who said they'd show up, I counted 22, but those were some of the best and brightest and made up in quality what they might not have reached in quantity.

Although the mayhem I anticipated never materialized, the event went well on the whole. Among other local luminaries, Dwight Silverman from the Houston Chronicle made his presence known and showed off his laptop with the recently-installed (and now, reviewed) OS X Leopard running Windows XP and Ubuntu under parallels.

I got a chance to speak to, and enjoy, a diverse group of users all of whom I haven't matched up to usernames yet. There was Brew Bird (I think), a BSD programmer and early ISP pioneer from Clear Lake. Prien 715 spoke articulately about the joy of programming CAD in C++. JGuthrie shared some hints about blogging and not getting caught. I saw Drachenstern leading a small group in discussion of Linux forensics and intrusion. But, conversation was blurringly fast and as the night wore on, increasingly blurry. (If I forgot you, or screwed up your username, please contact me at athloi AT yahoo PERIOD com).

The tshirts kindly provided by Sourceforge/Slashdot were a big success, with people clamoring for one and not content -- at all -- until they were handed out. TechGeek catalogs were a similar hit, with the clod of them I handed over to someone vanishing within a few minutes into jacket pockets.

I can barely remember much of what happened. I remember broken glass, loud music, a crowd of people smoking cigarettes in traffic, and then security asking me was a Slashdot was. In another ten years, I'd like to do this again, especially if I have a top-notch health plan.

Users replacing specialists in IT -- and technical writing

2007-10-30T08:55:00.000-07:00

Forget outsourcing. the real threat to IT pros could be Web 2.0. While there's a lot of hype and hubris surrounding wikis, mashups, and social networking, there's also a lot of real innovation--much of it coming from increasingly tech-savvy business users, not the IT department.^{^}

Developers and IT staff are facing the same situation technical writers face, which is that as users become more knowledged about technology, they need less of the standard functions (write the manual, install the operating system) we are accustomed to provide.

This is positive, in that it liberates us from some of the really mundane tasks, but it means that we are viewing users for whom a conventional manual is useless until about page 78, when the information they really need starts to appear. Even more, users are identifying with being technologically savvy and now want information that boosts them ahead of where they'd be if they just starting playing with the software on their own, assuming correctly that it works about the same way the rest of their software does.

IT departments are going to find that with the resources available to their users, they are going to have to concentrate more on making things work better, not just making them work, which is going to put them in a position closer to development. Similarly, technical writers (like interaction designers) will find themselves becoming enmeshed in projects from start to finish, providing feedback on what the user would think or understand for any proposed part of the software.

While some are going to see this as more stuff dropped on their desks, remember the first paragraph of this blogpost. Less stuff is going to be dropped on your desk. There may be some overlap between these two stages, but over time you may be heading toward more responsibility and more fun at your technical writing job.

Amazon, those silly fascists

2007-10-24T15:57:00.000-07:00

"Want to write a customer review?

To write a customer review: you must have used this account to complete a purchase* of an item from Amazon.com. Please wait 24 hours after your first purchase before writing a review."

Were they always this crafty? This policy might make sense, to keep down the sheer amount of vandalism that seems to occur on the internet. I'm not ready yet to pay their inflated prices for what I can find used at indie bookstores. I keep a steno pad in the car full of titles I'm seeking, and so far, no bookstores have asked me not to write down items in it.

DRM-free movie

2007-10-24T15:39:00.001-07:00

Back in 1995, Bill Batchelor thought he could make a film funnier than Hollywood's best efforts. Only difference was that Bill was using one-three-thousandth the budget of films at the time. The result, "Tufa: The Name Means Rock," was a sizzling satire of rock and roll culture and the eternally larval immature humans it produces. You can download it now in .AVI or .MPG format, DRM-free and contract free, from this page.

Tufa: The Name Means Rock

Hilarity linkpost

2007-10-17T12:32:00.000-07:00

Some of the goofy stuff that's infesting my world.

INSERT COIN - Man exploits the configuration language of HP printers to make them display random slogans, then wonders why none of us notice.

Mutant PEZ - These do really look like they came right out of the collision of an art convention and bored teenagers, but some are humor cryptic enough to jostle cynics.

Women in the Sciences

2007-10-03T09:19:00.000-07:00

As a recent press release indicates, women are being scared away from the sciences in part because of what press and academic institutions are calling a masculine atmosphere: outnumbered three to one, women pay more attention to this fact and find it unsettling.

While I'm not going to get into the nature versus nurture debate at all, I'd like to take this a step further and point out the geeky nature of working in the sciences as a primary factor as well. While I'm proud of being a geek, geek culture is deficient in its understand of women because many geeks find it difficult to overcome self-confidence deficit in approaching women for purposes of courtship. The result is a community that is unsure of whether to treat women as sexual objects or tomboys, and has no idea of the middle ground.

In our society in general, with its materialistic focus on women as either partners or business objects (whether in the boardroom or the strip club), it is hard enough for a man to interact with a woman without The Sexual Thing intervening. Do we wonder enough "Is she interested, or is this just friendship?" or not enough?

My suggestion is that we follow animal instincts. Most creatures have elaborate courtship rituals that are recognizable a mile away. A male bird struts and fans his tail, or a lizard drops a red flap of skin in a rhythm that suggests either advertising or that he's found a female lizard of interest. It is that our current dating process is so casually indistinct from normal conversation that logical-minded geeks find it baffling, and women find themselves caught between business roles and reproductive ones.

If we want more women in the sciences, we need to get geeks accustomed to interacting with them as friends who are also feminine, and we need to get courtship to become a formalized process so we'll never mistake it for casual interaction. This clear division allows logical minded men and women to know in which capacity they're interacting, and will make the sciences less threatening to women as a result.

Why to be leery of user feedback

2007-09-12T11:00:00.000-07:00

As technical writers, we often get user feedback, either from internal groups, internally tested groups, or from the internet at large. Here's a little warning about taking results from that last group too seriously, in the form of a critique of user feedback when the users can communicate between each other as they can on the internet. Basically, it's a feedback loop that amplifies negativity or positivity but misses any reasoned middle of the road input.

There's a similar effect with internally tested groups, which is when you ask a bunch of your users questions. They are impressed with official looking people or situations, and have respect for science, so making the whole process seem scientific or psychological in nature makes them more self-aware and more prone to respond with what they think sounds good, not what is accurate. I think some of our best results came when we sent in the intern with frizzy hair, sloppy clothes and a glazed expression because people just said the first thing on their minds and it happened to be most of the truth.

Webworks search

2007-08-29T13:41:00.000-07:00

A quick glance over the Webworks website showed me no search. So here's a hacked Google search to keep you from going nuts. View source on this page, open a text file, paste in the goop you see in this post, and then save as anything.html and double click for easy searching.

If they add one later, I'll remove this then-useless post.

Customer support basics

2007-08-16T07:37:00.000-07:00

Recent news tells us that movie rental firm Netflix has returned to the human call center for supporting its products, reversing a decision to use email entirely. I think this is a positive change.

Until AIs are fully able to understand our questions and not just recite data but think up best practices responses and adapt them to the situation specific to each customer, humans are a necessary resource for questions that do not fit into categorizable types. These are the "exceptions," because everything else neatly fits a type.

For those questions that do fit standard types, a well-written FAQ placed prominently on the website can make a big difference, especially if the company is smart enough to embed helpful forms within it (a question "How do I contact you?" should link to a form or ideally, have the form embedded within it).

A good FAQ saves massive amounts of time over talking to a human being if the question is both one that is frequently asked, and one for which the general answer does not change. Answer the archetypal question with an archetypal response, and direct the exceptions to the call center.

Even more, a simplified website can save the customers much headache. Few people have the time to sit down and take a thesis-level examination of the website design, scratching chins and asking themselves, "According to the framework of ideas presented here, where is it most likely that a given item of customer support data is hiding?"

We the customers want five-section websites with clear site maps, utilities to help us put services to good use (UPS's package tracking and Sprint's "How many minutes have I used?" come to mind). We want to be able to find, for each product, a subsite that also divides into not more than five sections, one of which should be a legible FAQ.

The good news is that you can save millions on marketing-speak and buzzwordy Flash animations. They do not enhance our experience at all. They are only useful for people in their first week of web usage, who think it is charming and wonderful that your cellphone or printer can fly across the screen and talk. Otherwise, they are an infuriating obstruction.

Think of your customer as someone in the trenches. The kids need to be fed, the spouse is wandering around aimlessly and needs to be redirected to an essential task, the phone is ringing with some well-meaning idiot from the city asking if your water supply is contaminated, and work the next day requires preparation. In the meantime, the letter that needs to go in the mail tomorrow won't print because the printer driver isn't installed.

You have about three minutes to win over this customer, and preserve the fragile surface tension of complete satisfaction with a product (within bounds of sense, of course). If they cannot get your product to work after visiting the website, clicking the logical option, and/or downloading the software, you are making a grave error by sending them away displeased after wasting their time.

None of this is difficult. It is not high-IQ work to write a perfect FAQ, nor is it genius-level engineering to come up with a printer driver that works right every time. Nor will it be noticed. If you do it, people will grunt and move on. But what you have gained is that they do not remember an obstruction to their path, so when they next are thinking of the printer to buy, their mindset begins with "Well, the Borokowski B2004 worked really well for us the last six years, so let's see what Borokowksi printers are on the market right now."

This is what quality user support, quality documentation, and quality user interface design get you: a chance at customer loyalty. It's cheaper to retain a customer than make a new one with a barrage of advertising toward an advertising-numb audience. If your business is thinking toward the future, you're not asking dumb questions like whether switching support to email only will save you money. You know the answer is that it will, but it will cost you loyalty, and so like Netflix, you'll eventually find it wiser to switch back.

(Original flameout on Slashdot, The Art of FAQ writing, is being quietly ignored here.)

Why most women (and many men) avoid IT

2007-08-06T11:54:00.000-07:00

Slashdot covered a story attempting to find out why fewer women are going into IT. They tried for the usual answer, which isn't political so much as it's convenient. You say that the churlish attitudes of geeks drove them out. I think it's something entirely different.

Most women, and many men, don't want to work in IT because the working conditions are terrible. First, you as a worker are fodder for replacement. Your coworkers are all geeks without lives, so they're thrilled to stay until midnight for free pizza. Management are the only people who can stand being between geeks, who are socially incoherent, and marketing, who have lied so long truth is an oxymoron to them. Your goverment is importing more workers who are even less critical to replace the native-born, who in every nation on earth tend to be less motivated by raw financial desire (what some call "greed").

All together, everyone is working to make personal profit by selling ephemera like software, operating systems and hardware. The high profit margin raises the competition and means that He with the least life wins, because those who dedicate themselves entirely to the job are most valued. He who asserts that he would rather spend time at home, or doing something other than the geek-approved activities of installing Linux or playing video games, is seen as "not dedicated." IT is the most corporate of all industries, in part because it tries to be the most easy-going, and that easy-goingness then becomes a good way to manipulate people. But we get free sodas!

A woman (and many men) who might want to someday be married, have a family, and have some reason for being alive other than going to work where she gets a title and two video screens, is not going to jump at a chance to be in IT no matter how good the money is. She knows that she will be fodder in competition which is a race to the bottom, with those who do nothing but the job coming out ahead. Many industries are like this, and increasingly, the smarter people are getting way from them. Who can blame them? It's better to have a job and a life, than just to have a job, even if that life is a quiet life of family and humble pleasures. (Some men want this too, but show most men a Big Title, a big income and lots of shiny objects, and he becomes a blue jay with a master's degree.)

In this, I think, women as a demographic have surpassed men in basic reasoning skills. They are valuing life more than money, and that is a statement of incredible maturity. Given that most of my male friends are still busy playing video games, buying CDs and going to concerts, I think maturity visits the male genre later. The question is, is it too much later, like 35 or 50, for it to matter?

Men should look toward their women for wisdom, because left to their own devices, men will create a nightmare IT industry. In this nightmare, hours worked is a more important metric than quality of product. Because all of the software is buggy, we spend endless hours working around it, as our creativity strangles itself and dies. I see this nightmare coming true.

For example, this blogspot software crashes if you use a window target in an outbound link. That's a fundamental need for any software, since you don't want to direct people away from the site, but keep them there. But blogspot.com is highly rated and probably is better than its competition. What does that tell you? Anyone who has sat through the agony of a Linux install only to find out that highly-rated software can't do what they need, or installed Windows and watched it instantly become inundated with viruses, can tell you the truth: our IT industry is producing crap and praising it highly but cheaply.

Smart men and women might want a part of that, and for many of us, we're drawn to it because we love technology. But less so, as the industry grows and gets more corporate. I think it may be that smarter men and women have forsaken those big paychecks and fancy homes in California for a saner lifestyle, and if it takes a women's revolt against IT to tell us that, more power to the ladies.

Original flameout on Slashdot

Web 2.0 is insane

2007-08-01T11:32:00.000-07:00

I finally signed up for Twitter, only to find out that my sneaking feeling that I'd never use this again is still there. What is the purpose? So really bored people can see the mundane details of my life, as if they'd care? And if they do care, from what am I helping them escape? It's too egomaniacal for me. I'll post regular updates at Twitter, but don't expect the blow-by-blow dramatization of a life that really lacks that kind of importance.

I was very please with John Dvorak's condemnation of Web 2.0 as the next bubble about to detonate. He's another person who gets paid good money to state the obvious, but he does it charmingly, like the Chronicle's Dwight Silverman and my old neighbor from Austin, Bob LeVitus. Bob likes Macs but he's OK otherwise.

Every single person working in the media today who experienced the dot-com bubble in 1999 to 2000 believes that we are going through the exact same process and can expect the exact same results—a bust. It's déjà vu all over again...Each succeeding bubble has been worse than its predecessor. Thus nobody is actually able to spot the cycle, since it just looks like a continuum. I can assure you that after this next collapse, nobody will think of the dot-com bubble as anything other than a prelude.

You preach it, John C. Dvorak. I started with the web in 1992 after much experience in FTP, BBS and Gopher information serving. I've seen the trends come and go, and experienced the wonder of hearing otherwise sane people repeat dogma that's clearly unrealistic. I don't hold it against them but it still makes me uneasy. Bubble 2.0 is the latest and most inflated of these bubbles, which are created when the market hypes trends that do not generate wealth, but move it around convincingly. It takes a few years to find them out and then, whammo, the markets must equalize and consume all that phantum, unearned, unreal wealth. Same as with the adjustable rate mortgages (ARM-and-leg mortgages). We played, now we pay.

Technical Writers vs "Tech Writers"

2007-07-16T09:40:00.000-07:00

Blogs seem to be a combination between homebrew journalism, high school theatre department "poetry," a professional clipboard and a diary. I don't know if this is a blog any longer, because I agree with Jakob Neilsen that professionals should heed this advice: "To demonstrate world-class expertise, avoid quickly written, shallow postings. Instead, invest your time in thorough, value-added content that attracts paying customers."

I'm trying.

Today's entry is one of vital importance to anyone hearing buzzwords without context. Technical writers, or "tech writers," are not technology writers, who are also called "tech writers." From Slashwrists:

Technical writers, sometimes called "tech writers," write manuals and help systems and procedures to help make sense of technology. We are unrelated to "technology writers," who depending on which one you encounter, may be people who failed to fill out admission papers correctly at the asylum or intelligent commentators.

Technical Writing

The Changing Role of Technical Communicators

2007-04-11T14:20:00.000-07:00

Some people consider technical writers to be an add-on to their application design and development process, and I think this is a mistake, although it makes our jobs easier. When we're add-ons, we show up after everything else is done, interview our subject matter experts, check facts, take screenshots, and then publish. But this also leads to a cursory treatment of the material, and user guides or help systems that although not factless are without a clue as to the best practices, or even common practices, that confront users.

This is a shame, since technical writers as those who have to explain how a software will work in the daily life of a user are those who can understand the whole of the product in two contexts: why it does what it does (technical), and what practical real-world purposes does it address (user). To write a quality UserGuide, helpsystem or even flashcard help, the technical writer must first acquire this type of familiarity with the product. And all of that is lost when the writer comes in late to the party to sweep up the shop floor with some timely but detached technical writing.

I understand the gunslinger mentality of technical writing, which prefers this approach, because it means the job's there for a few months and then the writer rides off lonely into the golden sunset, six-gun (presumably) thrown over a shoulder. I wonder about how well this serves users or employers, because it seems the most comprehensive view of the product walks out the door when the contract's over. I wonder about how well this serves technical writers, as it puts them in the role of perpetual wanderers who never have any actual stake in the product they're explaining.

Renovating Yahoo mail

2007-04-11T12:03:00.000-07:00

About six months ago Yahoo went on a renovation binge for their long-lasting mail service. They improved many things, but they missed the boat: they tried to make it "act like" Google mail without having what Google mail has used to win new users, which is a comfortable and intuitive interface.

What bothers me most is that I think highly of Yahoo as a company, and they seem to be completely missing a boat. They equated Gmail's success with having a fast and flashy interface, and improved on it in many ways. The drag and drop feature, for example, is brilliant. The use of folders is more intuitive. Their division of the screen into clear focus areas is superior to Gmail's floating windows.

But where Google remains champion is efficiency of use and fewer barriers to the user. Yahoo mail still defaults to an uninformative front page, and loads very slowly. Their spamtrapping is primitive, and seems mostly to punish good users who have links in their signatures. The interface for composing mail, like that of reading mail, uses a confusing array of different button and link types, none of which seem to be grouped by function. They're grouped by convenience for either developers or marketing people. I can't tell which.

The upshot of this is that Yahoo! spent probably a load of money and time to make a product that is going to lag behind despite their changes. They threw everything but the kitchen sink into the mix, when what they needed to do was take a careful study of how people use mail.

Update: Team member Ryan Kennedy kindly wrote back and explained that the new Yahoo mail predates Google by a good length of time, having been purchased from a third company and then developed in house. Thanks Ryan!

Mitigating user annoyance

2007-03-26T08:14:00.000-07:00

Jakob Neilsen, in this week's Alertbox, gets it right once again when he states "Fixing annoyances won't double your business metrics the way fixing usability catastrophes will. But, eliminating annoyances increases customer satisfaction and user loyalty, and thus improves the long-term business value of the site." I'd like to add something else: a user hung up on an annoyance does not remember a good experience, and is less likely to adopt technology in a friendly manner. Make a good interface, make a happy user, and everyone in technology benefits. Alienate people and you perpetuate those annoying jokes about computers and bad attitudes.

Speaking of how to fix interfaces, I noticed that Blogger takes the user to an error page if there's a lack of a closed tag in an HTML post -- but this error page is a dead end. There's no button to edit, and clicking back on most browsers (surprise!) does not retain any changes made. This is an exceptionally brain-dead example of a user annoyance that's easily avoided. They probably haven't gotten around to it, but they did just take away three minutes of my life I'll never get back through poor interface design.

The future of markup-enabled documentation

2007-03-26T07:16:00.000-07:00

I was intrigued by this recent writing:

"The most commonly-stated reasons for adoptingstructured documentation techniques include:Automation, Reuse, Single-sourcing, Productivity gains(resulting from the above)
However, none of these (or other) advantages require structuring at all. Non-SGML markup languages such astroff or TeX, and even help-authoring tools likeRoboHelp, all allow automation, reuse, and single-sourcing.

Another purported benefit of structured authoring isthat it enforces consistency both within a documentand across a suite of related documents. Again, structure is not necessary to gain this benefit: a properly-designed style sheet (combined with good old-fashioned peer pressure) is sufficient."

Structured Authoring: A Critique

I agree on some levels: structured documents, like virtualization, are an overhyped trend.

On another level, I find them useful in that they are often machine parseable.

On still another level, I find the convergence of RDFand XML interesting as XML is a structural markup,while RDF is a value-typing/definitional markup.

Kollar made some good points about the utility ofsimply a style sheet and some common sense. I thinkthe dumbing-down of authoring to the point wheremachines could do it is a silly idea.

On the other hand, I like the thought of writing information intoan XML format, tagging it with RDF-style definitional markup, and then putting a kind of data tainting on itso it knows where to go, whether a public CMS or a private intranet. Letting the machines work for us, in other words.