Netflix My Net-Docs

Meanwhile, in an alternate universe, the following message appeared on a website:

This site is only available for viewing next Thursday, from 2pm to 3pm. If you would like to view it after that, we can mail you a printed copy in 7 to 12 business days.

Actually, this isn’t too far from reality. Do you know there are people who still:

  • drive to a bank to pay bills, when they could do it online?
  • mail printed photographs to their family, rather than email them?
  • manage documents as part of a group, with each group member keeping their own duplicate copy?
  • watch movies and TV programmes according a broadcaster’s schedule?

The last point is particularly interesting. Why is it unacceptable to have a website (or any online content) that could only be viewed certain days and times, but it’s acceptable to have other content that’s only available certain days and times. Either scenario is ridiculous.

Through downloading, online reruns available on various broadcasting websites, and streaming services such as Netflix, gone are the days where you have to wait for a day. In addition, some of these services allow you to enter meta-data about your preferences, and to rate what you’ve seen, enabling the service to suggest content that might interest you. On certain sites, you can also add comments, which is pretty tricky to do using a television.

We’re therefore seeing entertainment content catch up with the principles of informational content, namely:

  • available for viewing any time, anywhere
  • customizable
  • permanent
  • enabling two-way communication

I can imagine a not-too-distant future where our children and their children will look back and laugh as they cry: “You mean you guys actually drove to a store to watch a movie? And there was actually stuff that wasn’t online?!”

The horror, the horror…


Doc Men

Mad Men is a highly-acclaimed and extremely addictive TV series set in an ad agency in the 1960s. This show is so popular that other networks are copying it. This fall, ABC will showcase Pan Am (think Mad Men in the sky), while NBC will air The Playboy Club (think Mad Men in Chicago). All these programmes reflect a nostalgic renaissance in the 1960s.

I was born in the 60s (1966 to be exact) so I have no memory of them. All I know is how they are represented. Growing up in the 70s and 80s, the 60s were the decade of hippies, Vietnam, flower power, Woodstock, sex, drugs, rock and roll. (Can one be nostalgic about nostalgia?) But this “groovy” world is not the one in these shows. It is the anti-hippie world of wealth, power, privilege, and sharp suits with thin ties. The only drugs on Mad Men are cigarettes and alcohol, usually in vast quantities.

We long for a certain era because we perceive it had something positive that the present does not, or that it did not have something negative that the present has. The 60s had sexism and racism, but they did not have the mad stress of today, where you can be online for work or play 24 hours a day.

The 60s had none of the political correctness which have culminated in so-called “human rights commissions”, where money is given to “victims” due to hurt feelings. One of these commissions rewarded money to a patron who was offended by a comedian during a live show.

In the 60s, people and governments generally lived within their means. Today, individuals and all levels of government have massive levels of debt. In the 60s, western nations regularly intervened in other countries. Today, they are reluctant to help out as citizens in other nations are slaughtered by their leaders, lest they be labelled “imperial”.

These shows, then, symbolize an era free from our repressive and culturally hyper-sensitive world. The political incorrectness of this time is encapsulated in its ads and educational films. Hilarious to watch today, they paint a picture of a simpler time, but are offensive by today’s standards.

With that, I offer several fictional examples of various educational and corporate communications. Enjoy the ride back in time…

TV Ad for a Garbage Can
Introducing the new Maxo-Garbage can. It can handle any kind of waste that you can throw into it! Food waste, paper, cardboard, pop cans, glass jars, packaging – all kinds of garbage. It all gets mixed together in the amazing Maxo-Garbage can. It has easy gliding wheels to help even the smallest woman move it – nice hauling, there, Mrs. Jones! Now it’s off to the garbage dump and on to the incinerator with contents delivered by Maxo!

The Canadian Immigration Agency
(A high school education film.)

The Canadian Immigration Agency helps people from all over the world to settle in Canada. Let’s follow a family from India as as they make their way over to a better country.

Meet the Singh family: Abhijay, Jawahar, Utkarsh, Viraj, Saptanshu, Sushila, and Nilambari. Boy, those sure are funny sounding names, aren’t they? The Singhs are on their way to Canada. We’re profiling the Singhs because they were the only ones that had a last name we could pronounce.

The Singhs have arrived in Canada during the cold winter. Looks like Mrs. Singh should have packed some winter coats! They’ll learn soon enough to get used to the sub-zero temperatures.

The Canadian Immigration Agency will help this family settle in. We know it can be tough for families to adjust. Look – there they are now looking for a place to eat. Too bad the nearest Indian restaurant is 2,000 kilometers away. There’s Mrs. Singh doing some grocery shopping. Sorry Mrs. Singh – there’s no curry in this supermarket! It looks like they’ll have to eat Canadian food for a while. But, as you can see, the Singhs seem to be adjusting nicely. See Mr. Singh carving that big Christmas turkey? Don’t forget the gravy!

The Canadian Immigration Agency: Helping strange foreigners become normal people.

How to Fix Anything: A User Guide for Ladies
Hey ladies – fixing things is easy! Just follow these simple steps:

If it doesn’t have too many moving parts or any sharp edges – Ask your son for help, or just call on a neighbour’s boy down the street. They should be able to help you! And no – you don’t have to pay them – sincere praise from a grown-up is all the reward they need!

If it has lots of moving parts or sharp edges – Ask your husband.

Note: If you don’t have a son or husband, or access to one, then you’re just plum out of luck!

What Does a Technical Writer Do?
(Another high school education film.)

Meet Joe. He’s a technical writer. He writes the instruction manuals that go with products so that people can understand how to use them. It’s an important job, because if people can’t use the product, then they’ll have to call up the company, which then has to immediately send a local repairman out to fix the problem, at the company’s expense, of course. We sure don’t want that to happen, so it’s important that anyone can understand what he writes.

The typewriter is the main tool of the technical writer. Today’s typewriters allow you to go back and correct an entire word! Think of that – no more wasted paper sheets. We are truly living in a modern age.

Here’s Joe at work now. He is working on a very important guide – a user manual for a washing machine. The first rule of technical writing is that you have to write with the end user in mind. This means that Joe must write the guide so that even a woman can understand it.

Joe is chatting with Henry, the designer of the washing machine, as they each relax with a cigarette. Henry has to be careful not to smudge the draft of the guide with his highball. Afterwards, Mr. Singh comes by to clean up the big mess they made.

Joe then takes an extended lunch with Betty, his attractive secretary. He’s probably going to talk about all of the wonderful documents he’s working on. There they are now, back from their long break. It must have been an exciting discussion because they both look so tired! Joe and Betty sure do spend alot of time together – it can only mean he’s working on a really big user guide!

Well, it’s been another full day for Joe as he comes home. Joe makes a good living as technical writer, allowing his wife and family to have nice things. Doesn’t Joe’s daughter have a swell dress?

So consider becoming a technical writer – your wife will be glad you did!

Ultimate Doc Tease

Image result for Ultimate Dog TeaseThe Ultimate Dog Tease YouTube video has been viewed millions of times. It’s a hilarious clip of an unseen owner unbearably teasing his dog about food. If you haven’t seen it yet, watch it now, then return to this article.


Pretty funny, eh? Andre Grantham, the creator of this video and several other talking animal videos, is from Halifax, Nova Scotia. He was unemployed when this video was released, but soon received a job offer.

What makes this video so funny is its simplicity. There are no special CGI talking animal effects – the movement of the dog’s mouth is all natural, as is the dog’s ever hopeful expression.

Because we don’t see the owner talking, and because the “talking” done by the dog doesn’t match the dog’s mouth exactly, it would be quite easy to dub in your own script. I’m not a video editor, but here’s the script I would write for this video:

Me: So I got this draft back.
Dog: Yeah.
Me: Yup – a SME took the time to review it, can you believe it?
Dog: Yeah.
Me: Anyway, I looked through the whole draft…
Dog: Looked through the draft, yeah.
Me: And the reviewer wrote on it..
Dog: Yeah.
Dog: Ohhhhwwww…’re kiddin’ me.

Me: Then I started working on this other guide.
Dog: Yeah. 
Me: A user guide. 
Dog: A user guide, yeah. 
Me: It had lots of really nice screenshots. Very pretty.
Dog: Yeah. 
Me: We were all set to release the guide, but then you know what?
Dog: What?
Me: The marketers changed the screen design!
Dog: Ohhhhwwww…..

Me: Then my boss called me into his office. 
Dog: Yeah.
Me: He said we’d be getting a brand new content management system.
Dog: What would be in it?
Me: Well, it would have versioning, multiple outputs, workflow management..
Dog: Workflow management, yeah.
Me: …be DITA-based and fully customizable.
Dog: Yeah.
Me: My boss said we could get it real soon.
Dog: Yeah.
Me: But to pay for it…
Dog: Yeah.
Me: …he’d have to lay off me and half the writers!
Dog: Ohhhhwwww…..

Too many notes

Related imageThe spectacular 1984 film Amadeus about the life, music and madness of Mozart includes an amusing exchange between the Austrian Emperor Joseph II and Mozart. The Emperor, having just heard Mozart’s opera, gives the following feedback:

“Your work is ingenious. It’s quality work. And there are simply too many notes, that’s all. Just cut a few and it will be perfect.”

To which Mozart replies: “Which few did you have in mind, Majesty?”

The organizers of an electoral recall in British Columbia have run into a similar problem with a document. Elections Canada has rejected the application because it contains too many words.

Or does it? Chief electoral officer Craig James turned down the application because he felt that the acronyms MLA and HST are not two words, but eight. If you replace these acronyms with the words they represent (member of the legislative assembly, and harmonized sales tax) the 200-word maximum is then exceeded.

This is a documentation limitation that only a mindless bureaucrat could come up with. Even if you do count an acronym as more than one word (an obviously ridiculous standard), why would the maximum number of words in an application of this importance be set as low as 200? Surely one page (or about 450 words) would be a more reasonable limit?

In the meantime, the petition organizers need to find a good editor and give the following instructions:

“Note: There are too many notes in our note.”

Jay Leno’s User Guides

See the source image

Avid car collector Jay Leno wrote a hilarious piece on car user manuals, observing how much they, and their readers, have changed over the years.

Earlier guides assumed the user actually knew how cars worked and could easily service them themselves. Today’s guides assume (correctly) that the user knows next to nothing, except perhaps where to put the gas in.

Here are some of Leno’s funnier examples:

A. Old guide: Removing the Cylinder Head: Obtain a block of wood approximately the size of the combustion chamber and place this under the valve heads on the number one cylinder. Press down on the valve collars and extract the split collars. Remove collars, valve springs and spring seats. Repeat for the remaining five cylinders. Valves are numbered and must be replaced in original location. Number one cylinder being at the rear, that is, the flywheel end.

New guide: Changing the battery: Battery disconnection, removal or replacement should only be carried out by qualified personnel. Consult your dealer.

B. Old guide: In the event you need to remove the engine, gearbox and clutch, in the event it is necessary to carry out a repair of all the above units, notice that the gearbox may be removed from the engine when the floorboards have been removed and the rear of the engine has been supported. Removal of the gearbox will give access to the clutch.

New guide: If engine warning light goes on, consult your dealer. 

C. Old guide: To raise the headlamp beam, rotate spring-loaded screw on top of lamp clockwise. To lower beam, turn counter-clockwise. To adjust headlamp beam left or right, slacken the two hexagon-headed screws, one on each side of reflector rib assembly, and move the reflector assembly to the desired position. 

New guide: Do not attempt to adjust headlights. See your dealer.

Some other notes from old guides include:
  • An explanation of the correct “ignition point settings”, showing how to “adjust the distributor and vacuum brake”. The guide states: Your Ford dealer can make this adjustment for you, but there’s no reason you can’t do it yourself. Right, and while your at it, you can be servicing your washer and drier.
  • A guide for an old car made partly of wood states: If flames start licking over the front of the hood, shut off fuel and increase speed until flames blow out. Yikes – talk about a “hot rod”.
  • This one is simple and to the point: After 1,000 miles, disassemble engine, check everything, reassemble. Got it!
All this shows there’s only two things that affect the content of a guide:
  • the product being document
  • the user reading the document

They just don’t make users like they used too…

Inspired by truth

Image result for Inspired by true eventsInspired by true events is a tag line appearing in some new films. This slogan replaced the previous antiquated version: Based on a true story. It is also complete nonsense, because all films, indeed all art, is “inspired” by true events, because all art is inspiration from actual life.

This is a classic example of marketers taking a perfectly good piece of text and ruining it with meaningless gray words so as not to offend anyone. I enjoy fictional works as much as anyone, but please don’t mix my fact and fiction. I would rather see a documentary than an artistic film claiming to be “inspired by true events”, because in a documentary, I’d assume everything I see actually happened. In the “inspired” film, I wouldn’t be so sure.

There are writers, and then there are technical writers, and never the ‘twain shall meet. Technical writing is as different from fictional writing as house painting is from artistic painting. Writing a novel does not qualify a person to be a technical writer. It only qualifies them to be a story-teller.

We don’t tell stories. We don’t spin yarns or tell tales. We explain the facts; the what, where, when, why and how. We don’t get into feelings or characters. We remain cool and unemotional in our work. You may try to change us to novelists and ad men, but you will fail.

We are logical. We battle confusion and uncertainty.

We are Vulcan. We are the Borg.

Resistance is futile.

3D Documentation

Related imageI recently experienced the latest technological marvel: 3D television, and have to admit – it is spectacular. The images have an incredible depth, and also can appear to “pop out” towards you, for a virtual virtual reality experience. But it ain’t a cheap experience.

A 40″ Samsung 3D TV currently sells for $2,500 CDN. The special glasses required sell for $250 a pair. For a typical family of four, that means an extra $1,000 just for the eyewear! And, you have to buy a new Blu-Ray player and new 3D Blu-Ray disks. And a new type of cable to connect it all. Didn’t we just go from DVD to Blu-Ray? What’s next? 4D TV?

To be fair, 3D TVs can also convert regular 2D images (regular TV channels and DVDs) to 3D, but the effect is not as great as with a true 3D source. If nothing else, 3D TV will drive down the price of regular HDTVs, which themselves are light years ahead of CRT TVs.

The price will have to drop considerably for this new technology to have any chance of succeeding. If it does, it is proof that people are willing to spend just to get an extra dimension. However, dimensions don’t just apply to images: they also apply to information.

The dimension of information is its scope and quality. If the contents of a guide have a good dimension to them, it means they are in-depth, clear, detailed, meaningful and practical. If the contents lack dimension, then the guide is “flat”. A flat guide explains only the basic facts of a product, and not their relevance or practical application. A flat guide does not add value; a dimensional guide is the essence of “value-added”.

Adding dimension to a guide means including things such as:

  • clear explanations of all the concepts
  • a detailed glossary of all the terms; if a term is used in the definition of another term, it should be hyperlinked to its definition so the user can easily move from one term to the next
  • an explanation of exactly why a user would complete a task, before presenting the actual task steps; if the explanation itself raises another “why?”, then it is not a true explanation
  • different ways to accomplish the same task
  • relevant cross-references to other topics (but not too many because then the user will be overwhelmed!)
  • detailed screenshots, with all of the elements clearly labeled
  • a rich index that anticipates all the ways a user might look up a topic
  • a feedback form where users can directly comment on the usefulness of a topic

Don’t be flat. Take your docs into the next dimension. (No 3D glasses required.)


Image result for BlockbusterBlockbuster Video is going bust. Although they have not officially filed for bankruptcy, it seems certain they will soon have no choice. This comes as no surprise, of course. The very idea of driving to a store to rent a movie is as outdated as a typewriter or Windows 3.1.

People today get their movies through mail rental services, downloading (legal and otherwise), video on demand and even vending machines. The funny thing is that Blockbuster offers these alternate services, yet is still going broke. Why? Because most of its customers are simply not aware of these services, allowing other companies to corner the market.

Lack of awareness is a big problem for our profession. Users don’t know how to use products because the users are unaware. If helpful documentation is available, users don’t know it. If users do know that documentation is available, they don’t know how to find it. If users can find it, they don’t know how to effectively use it. And even if the users do know how to use the document, the document itself may lack awareness if it does not clearly explain what the user is looking for.

As a result of all this ignorance, many working products are returned to stores because the users could not figure them out. The goal, therefore, should be to create visible, usable documentation. Otherwise, you will get busted.

Olympian glitches

Related imageBefore an Olympics occur, there is another sporting event: the mad spectacle of various cities fighting over each other for the chance to host the Olympics. It’s as though five debt-ridden people are competing to acquire even greater debts. Afterwards, there is genuine surprise over the overspent millions.

Of course most Olympics lose money. When you create miniature cities of massive structures that will most likely be used only once, debt is inevitable. If there’s one event in the world that needs single-sourcing, the Olympics are it.

Still, I’m not a complete curmudgeon when it comes to The Games. I admit I enjoy watching the opening and closing ceremonies, and the Vancouver opening ceremonies did not disappoint.

Cauldron Calamities

To be sure, there were a few problems: some of the invited First Nation leaders were a bit late in arriving, one of the giant torch cauldrons failed to rise, and a hapless Wayne Gretzky took a painful ten minute ride in the rain, in a swerving vehicle, just to light another cauldron. It would have made much more sense to have a second athlete positioned right next to this second cauldron. This way, the show would simply have quickly transitioned from one lighting to the next, but I guess the producers wanted to build up momentum, and generate a few laughs in the process.

Another problem, of course, has been the weather. While it is true that Vancouver is experiencing one of its warmest winters in history, the fact is winters in general there are quite mild, making it a rather dubious choice to hold a winter game. Is it too late to redub these “the spring Olympics”?

Half full or half not?

Still, despite all these glitches, the games appear to progressing normally. It’s so easy to focus on the negative, but for every one thing that goes wrong, hundreds of things go right.

This is also true in documentation. For example, think of the features many online help systems have:

  • hundreds of topics explaining every concept, task, dialog box, and field
  • a TOC that links to all the topics
  • a powerful search function that can rank search results
  • an extensive index that anticipates all the ways a user might look up a topic
  • in-line glossary terms that allow the user to hover over a term and see a pop-up of its description
  • hundreds of cross-references
  • the ability for users to: expand or collapse the TOC, automatically synchronize an open topic with the TOC, save favourite topics, and directly submit feedback about the help
  • the ability for writers to: create reusable text objects, manipulate the order and hierarchy of topics, create and manage style sheets, conditionalize text and create variables

The code that allows all of this functionality is enormously complex, and I haven’t even covered spell-checkers. The fact is that modern documentation systems are open miracles.

Reviewers sometimes take these systems for granted and get upset when a glitch occurs during the review process. However, as writers, we also take our tools and technologies for granted, until glitches start occurring. Most can be resolved; some cannot, but that does not mean we throw away the entire document.

Perfect for each other

If only “perfect” Olympics were allowed to be staged, none would be.

If only “perfect” documents could be published, none would be.

There is no perfect document; perfection is only goal we can strive towards and never achieve.

But in the process, we can produce information worthy of a gold medal.

And the Oscar goes to…

Image result for OscarsThe Annual Distribution of Meaningless Awards to Shallow People, a.k.a., The Oscars, is fast approaching. This non-event is as useless as a Windows 1.0 user guide. The choices are completely subjective. Many great films and performances have lost out to lesser ones. One of the best examples of this is the masterpiece Citizen Kane, considered by many the greatest film ever made, which lost to – wait for it – How Green Was My Valley.

Now, many STC chapters have awards for technical communication. Unlike the Oscars, this is a useful awards event, if for no other reason than to have one’s work judged by others. Perhaps, though, to liven things up, we need to develop sexier categories:

  • Best Looking Cover Page
  • Best Performance by an Index in a Leading Role
  • Most Graphic Use of a Graphic
  • Most Outstanding TOC
  • Most Consistent Use of A Comma Before the Word “And”
  • Best Use of Bold and Italic Simultaneously

Of course, we’d have to develop a nickname for the trophy. How about the “Writey”?

Doubling Your Pleasure

This year, the Academy has doubled the number of nominees for best picture from five to ten. The official reason is to give less successful but presumably worthy films a chance. The unofficial reason is to boost ticket sales and film rental revenue.

This idea is as dumb as a bag of Oscars. Why stop at ten nominations? Why not have twenty? Or a hundred? Just as printing money lowers its value (something the U.S. is painfully learning), increasing the number of nominated films simply lowers the value of a nomination.

Things that are important are important because there are so few of them. The important things in documentation include:

  • the important information users need to know, as highlighted in notes and warnings
  • headings, including chapter and other major headings: headings 1 through 3, for example

Therefore, if you have too many of these elements in a document, you weaken the document. For example, if you have six Important notes on a page, the reader may likely ignore them all, since if everything is important, nothing is important. Better to group all these notes as bullets under one Important Considerations section.

As for headings – again, these need to be used carefully and sparingly. Too many chapter and heading divisions in a document dilute the document. You end up with a TOC containing 47 chapters, and a chapter with 37 heading 1 sections. Instead, group numerous separate smaller sections into one large section. Split a super-sized chapter into two or more chapters. Don’t force your readers to wade through a sea of sections. Combine, converge, and conquer.

By doing these things, you’ll create documentation that people can actually use. This is so much more valuable than a 13.5″ statue of a bald naked guy.