Tech Word

  • Subscribe to our RSS feed.
  • Twitter
  • StumbleUpon
  • Reddit
  • Facebook
  • Digg

Wednesday, 31 March 2010

A healthy-sized document

Posted on 12:23 by Unknown
The Obama administration scored a major victory with the passage of its health care bill, a massive 2,000+ page document . I wonder if every Senator and Congressman has actually read the entire thing; a Quick Start Guide would be useful.

This bill sounds great in theory: millions of Americans who were not previously insured now will be. Insurance companies can no longer exclude people with pre-existing conditions, which from the horror stories I've heard could include symptoms such as "breathing" and "blinking". Time will tell, though, if this bill will actually save lives. However, a new television show offers an enlightening perspective.

Jamie Oliver is a English celebrity chef who advocates healthy eating. He's exposed and improved the quality of meals served in the English school system. In his latest show, Jamie Oliver's Food Revolution, he visits Huntington, West Virginia, ranked as one of the the least healthy cities in the U.S. He is shocked to discover the high-sugar and high-fat processed junk being fed to schoolchildren twice each day.

Two scenes from this show will be forever etched in my memory. One is an experiment with some of the schoolchildren that goes horribly wrong. Jamie brings several young children into his kitchen-storefront. He takes out a chicken and shows them the good cuts of meat from it - the breasts, the thighs, and so on. What remains is the disgusting garbage leftover - the bones, cartilage and fat. He places these horrid leftovers into a blender, liquifies them, and adds artificial flavours and fillers, makes them into patties and deep fries them, to demonstrate how chicken nuggets are actually made.

At this point, Jamie asks the children if they would like to eat these nuggets, fully expecting that none of them will. To his shock, the children ask to eat them! Why? Because they are hungry.

In an even more disturbing segment, Jamie visits a classroom. He discovers that the children cannot identify basic vegetables such as tomatoes, potatoes and cauliflower. They can identify ketchup, french fries and hamburgers but have no idea as to where these items come from. In a later follow-up visit, the children have learned to identify the vegetables, but I've no doubt that this ignorance is common throughout the country.

Returning to the health care bill - the problem is that this bill does not directly address what is really killing and maiming Americans by the millions: poor diet, lack of exercise, and mental health issues including addictions such as smoking and drinking. This bill treats the symptoms of poor health, not the major causes or reasons.

It's important to be aware of symptoms vs. underlying reasons in our profession. It's a common perception that the purpose of technical communication is to instruct users on how to use a product or service. Although this is true, it is not the true reason, for we can always ask: Why do companies care if their clients can use the product? They care because if users can't use the product, they will either return it or call tech support, both of which drain profits. However, even that is not the true reason.

For the true reason, we need to understand that all belief systems have definitions of good and evil. In the free-market capitalist system, the definitions are:
  • good – anything that increases profits
  • evil – anything that decreases profits
Now we have the real reason, and not the "symptom" behind the need for technical communication. It's not to tell users how to use products, or to lower support costs, even though both these things are important. It is to maximize profits.

This is also the true reason because we cannot effectively ask "Why do companies need to maximize profits?" They just do.

Remember this in an interview. Technical communicators already are a disadvantaged minority, because we are a cost centre and not a revenue generator. Therefore, in a interview, you must show how you increased profits by decreasing costs.

Be good; don't be evil.
Read More
Posted in business, news, politics | No comments

Sunday, 28 March 2010

Size doesn't matter

Posted on 07:19 by Unknown
The Canadian government recently released over 2,500 pages of documentation. This was in response to pressure from the opposition parties regarding the controversy over how Afghan detainees were treated by the Canadian military.

2,500 pages sounds like a huge amount. The problem is that most of it was censored for "security" reasons, an explanation which the opposition, of course, does not accept. My first reaction when I saw the heavily-blacked out copies on the news was that it was a huge waste of toner and paper. The government could have spared themselves much grief, ink and trees if they had simply emailed everyone a document that only contained the non-redacted text.

Tech writers often get hung up size. Picture this conversation:

Tech Writer A: I'm working on a guide that's 300 pages!

Tech Writer B: That's nothing - I'm working on a guide that's 1,000 pages!

Tech Writer C: 1,000 pages? That's a lot - if you're a little girl...

Size just doesn't matter. The quality of a document is not proportional to its volume. Some shorter documents are useful while other larger ones are not. In fact, less is often more. Succinctness and brevity while remaining clear and thorough are the true hallmarks of quality.
Read More
Posted in news, politics | No comments

Thursday, 18 March 2010

No sex please, I'm neutral

Posted on 10:40 by Unknown
In an extreme version of single-sourcing, Australian officials issued an immigration certificate with the Gender field listed as not specified.

The document was issued to immigrant Norrie May-Welby, who was born a man but later had a sex change operation. The procedure included taking female hormones, but after several years, this person stopped taking the medicine and decided to become a "gender-neutral". "The concepts of man or woman don't fit me," he said.

Oops - I mean she said... I mean s/he said. (Damn these restrictive pronouns!)

A few points on this rather delicate topic.

1. Do the sex and gender fields of all government forms need to be revised to include "none of the above"?

2. If this answer to the above is "no", how does one handle rare documentation cases such as these?

Technical communication ideally is as digital as the computer file itself. That is, every topic, concept, state and procedure is clearly defined with no ambiguities. True or false. 1 or 0. Binary or death.

Now, the best way to avoid confusion is to explicitly define your terms. All objects, actions and items must be clearly described using non-technical words which themselves need no further definition or explanation. Otherwise you end up with sentences like this:

To folicate the nefigog, you need to parrelify the actrawan.

Unfortunately, uncertainties and confusion sometimes occur. Or to put it more succinctly - sh-t happens. What then?

It all depends on the dreaded probability factor, which is:

A. the number of users who may encounter this situation
times
B. the number of times they might experience it

If this factor is high, then it indicates a flaw in the design of the product itself. If the usability and repair budgets are exhausted, and there will be no fix forthcoming, it falls upon the shoulders of the lowly technical communicator to openly document this heinous behaviour, probably in a number of places, for example: the ReadMe, the User Guide, the Install Guide, and so on.

If this factor is low, the exception can still be documented, but less frequently. For example, in the aforementioned "gender neutral" problem, given the few times this will occur, I would add a brief note to the field description, something like:

Select a Gender: M for Male, F for Female, O for Other.

Note: If you select Other, you can enter more detailed description, because we're really curious to know just what the hell you are.
Read More
Posted in news, politics, science | No comments

When mail merges go bad

Posted on 10:16 by Unknown
697 former Parliament employees received a T4 tax form that belonged to somebody else.

Government House leader Jay Hill said the mixup probably happened when the employee lists were incorrectly merged with other addresses.

Responding to this documentation crisis, here is Mr. Hill's quote of the day:

"I often wonder when people sit and stare at these computer screens all day why there aren't a lot more errors like this."

Time to take a break from this screen, I think.
Read More
Posted in news, politics | No comments

Blockbusted

Posted on 10:01 by Unknown
Blockbuster 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.
Read More
Posted in business, entertainment, news | No comments

Thursday, 11 March 2010

Security breach!

Posted on 10:25 by Unknown
It's always entertaining to read about non-lethal lapses in security at a major event. Remember the debacle at the 2010 Winter Olympics? A man with false ID got within a few yards of U.S. Vice President Joe Biden before being arrested at the opening ceremony. You'd figure after spending almost a billion dollars on security, the organizers would be able to hire people who could spot phony passes. (I also wonder if the intruder got a refund, because, hey, opening ceremony tickets are expensive!)

Another security breach also involved the White House, where an uninvited couple crashed a State dinner, and actually met the President and Vice President. Security officials admitted there was a breach but said not to worry; the couple didn't have any weapons. Gee, that's a relief...

These incidents are actually symptoms of a much larger debate: balancing security with democracy. This has been a problem for society long before terrorists or 9-11, however modern terrorism has made the balancing act much more difficult.

On the one hand, governments have a responsibility to stop attacks and ensure their citizens are protected. On the other hand, they have to ensure they don't turn their nations into police states.

On a more personal level, regular people face the "security vs. freedom" question. Having a credit card is convenient, but can expose you to fraud. Driving a car gives you mobility, but you run the risk of death or dismemberment. Every day, we're always making trade-offs between safety and convenience.

Technical communicators are no different. One of the most difficult tasks in our profession is deciding what information to give to users, and what to withhold. Make no mistake - it is often in the user's best interest not to tell them everything possible about the product you are documenting.

For example, you may be documenting a web-based product which has a particular task that can be reversed or "undone". However, you may want to withhold that information, because by telling the user they can "undo" one function, they may assume they can undo other tasks, leading to disaster.

Another example relates to FrameMaker. If I were documenting this product, I would probably not tell users that they can:
  • combine conditional text conditions
  • include text insets within insets
because either of these actions actually creates further problems.

However, there is something much more valuable that the security debate teaches us: the importance of proper information gathering. 9-11 was a failure to properly gather, consolidate and evaluate information. The right questions were not asked of the right people.

Contrast that failure with how an Israeli security agent questioned Ann-Marie Doreen Murphy, a 32 year-old Irish woman who was trying to board an El Al flight to Jerusalem in 1986.

The conversation went something like this:

Agent: Did you pack your bags yourself?

Murphy:
No.

Agent: What is the purpose of your trip to Israel?

Murphy: For a vacation.

Agent: Are you married?

Murphy: No.

Agent: Traveling alone?

Murphy: Yes.

Agent: Is this your first trip abroad?

Murphy: Yes.

Agent: Do you have relatives in Israel?

Murphy: No.

Agent: Are you going to meet someone in Israel?

Murphy: No.

Agent: Has your vacation been planned for a long time?

Murphy: No.

Agent: Where will you stay while you’re in Israel?

Murphy: The Tel Aviv Hilton.

Agent: How much money do you have with you?

Agent: Fifty pounds.
(Note: This is less than what a single night at the Hilton cost.)

Agent: Do you have a credit card?

Murphy: Yes.

However, she did not; instead, she showed the agent an ID for cashing cheques.

The agent sent her bag for additional inspection. A bomb was discovered hidden in her bag. Her lover had planted the bomb, unbeknowst to her. (Something tells me they're probably not still a couple.)

Note that the bomb was discovered without any technical devices or sophisticated electronics . The agent simply used proper interviewing and behavioural observational techniques to discover the truth.

This is precisely what technical communicators need to do. Fancy documentation tools are nice, but they are no substitute for intelligent investigation.

When researching a document, you may have a conversation like this with a SME:

Writer: Is X true?
(where X is any statement of fact about the product you are trying to document)

SME: Oh yes, absolutely X is true.

Writer: Is it true all the time and under all circumstances?
SME: Uh yes, I think so. I'm pretty sure it is.

Writer: Well, what about in situation Y, or if you were to do task Z to get to X?
SME: Actually, in those cases, X is not true.

Writer: Thank you.

This happens all the time. It's not that SMEs are stupid or don't want us to do our jobs - it's that they are trapped in their world of code and are often not able to see beyond it. They often lack the holistic, big-picture view that technical communicators must have in order to successfully document a product.

People who are studying technical communication in school should also take courses in detective work and investigative journalism, because all tech writers are really detectives and reporters.
Read More
Posted in news, security, sport | No comments

Wednesday, 3 March 2010

Taxing my docs

Posted on 10:18 by Unknown

I recently attended an STC conference where one of the topics discussed was user-centred design. I met with usability experts and interaction designers whose sole job is ensuring that a product is intuitive and easy to use from a user's perspective, and not from the business's.

At the conference, I met someone who visited Intuit's usability lab in California. It's a multi-million dollar facility where they exhaustively test usability, bringing in many different typical users of their products. You can see the results in their software: TurboTax in the U.S. and QuickTax in Canada. I have QuickTax and I can say it is one of the most well-designed, user friendly and intuitive products I have ever seen.

So, if you want to create well-designed, user-centric documents, then study, use, and analyze
well-designed, user-centric products. For in the end, the document is as much a product as the product itself.
Read More
Posted in business, usability | No comments

The Sixth Sense

Posted on 09:37 by Unknown
We all know (and love) our five senses: sight, hearing, taste, smell, and touch. Apparently, these senses are not enough. Science, psychology, and the arts have been on the hunt for a sixth sense since the time people knew they had senses.

Candidates for a sixth sense include:
  • intuition
  • emotion
  • intelligence
  • extra-sensory perception (ESP)
  • equilibrioception - the ability to balance
As a technical person, one of the candidates that I find particularly interesting is a device called, (what else?), the SixthSense.

The SixthSense is prototype information device you can wear. It consists of a computer, a pocket projector, a mirror, and a camera. The projector projects visual information onto any surface. The user wears colored markers on their fingertips. The camera recognizes and tracks the user's hand gestures, kind of like in the film Minority Report.

There are many cool things that you can do with this device just by using your hands to virtually "draw" various shapes:
  • "draw" a magnifying glass to launch a map application
  • "draw" virtual shapes onto any surface
  • "draw" a frame to launch the camera
  • "draw" the ‘@’ symbol to check your email
  • "draw" a circle on your wrist to project a watch onto it
  • use hand gestures to flick through photos you've taken
Most importantly, SixthSense can detect different types of physical objects and then project additional, meaningful information onto them.

Examples include projecting:
  • live video news or dynamic news updates onto a newspaper
  • current airline departure information onto an airline ticket.
  • nutritional information and recipes onto food packages you are looking at the supermarket
  • book reviews onto a book
  • a person's favourite websites onto the person's shirt (yes, it really can do that!)
This device is a glimpse of a future world awash in meta-information. It is currently a prototype, and not freely available. However, the documentation we create is. For this, there are valuable lessons.

First - all technical communicators do have a sixth sense - the sense of information. And not just any information, but clear and meaningful information. We know, or can find out, what the user needs to know. We know how to give that information to the user. The only thing we don't know is what what we don't know. But we know that we don't know what we don't know, you know?

To find out what we don't know, we speak with the people who do know. These are the other people involved with the product you are documenting. Particularly important are the people who are working with the users who actually use the product. These are the salesmen, product analysts, business analysts and others who have direct contact with the end users.

Second - our documentation should be as helpful as a SixthSense device. It should:
  • "know" the user
  • know what the user needs to know
  • give them the information they need to know
  • tell them how to get more or different information
  • withhold information they do not need to know
Do you agree? If not, I'm not worried.

You'll come to your senses...
Read More
Posted in philosophy, science, technology | No comments

Gold, finally

Posted on 09:25 by Unknown
I admit I'm not a huge hockey fan. For me, the ability to insert a small, black plastic cylinder into a mesh just doesn't give me a warm fuzzy. However, even I have to admit it is remarkable that Canada won gold in both the men's and women's hockey at the Vancouver 2010 Olympics.

I agree it is somewhat sexist that Canadians have been focusing more on the men's win than the women's. Maybe it's because the score was so close. I think it's because the Canadian men's team lost to the same opponent (the U.S.) only a few days before.

Now, I admit I'm not a sports analyst (just a lowly information analyst), but I would say the Canadians won because they learned from the mistakes they made in the first game. The Americans, on the other hand, because they did not fail at the first game, had no mistakes to learn from.

Mistakes, therefore, are quite important. Before a draft is finally unleashed upon your readers, make as many bloody mistakes as you can; real nasty ones, if possible. Typos. Missing headings. Confusing overviews. Font failures. Awful grammar. Procedures missing steps. The more, the merrier.

Learn from your mistakes. Find them. Fix them. Then, when the software goes "gold", so too will your draft become golden.
Read More
Posted in news, sport | No comments

Krazy Karl Rabeder

Posted on 09:20 by Unknown
Karl Rabeder is an Austrian millionaire. But he's sad - so sad that he's giving away his entire $5 million fortune, to charity.

"My idea is to have nothing left. Absolutely nothing," he said. "Money is counterproductive --it prevents happiness."

Karl continues: "For a long time I believed that more wealth and luxury automatically meant more happiness," he said. "I come from a very poor family where the rules were to work more to achieve more material things, and I applied this for many years."

Later in life, his views changed. "More and more I heard the words, 'Stop what you are doing now -- all this luxury and consumerism -- and start your real life'," he said. "I had the feeling I was working as a slave for things that I did not wish for or need...I was just listening to the voice of my heart and soul."

So, he has moved out of his mansion into a small hut. I wonder Mrs.
Rabeder thinks of her new home.

If Karl's move is successful, he should write a user guide describing the process: The Millionaire's Guide to Living Poor. It could cover such topics as:
  • Filth is Your Friend
  • How To Eat Almost Anything
  • Got Mud and Straw? Let's Start Building A Home!
  • Saying Goodbye to Your 55" TV
  • Convincing Your Family that Poverty Builds Character (yeah, right)
I sympathize with Karl. Feeling sad sometimes is completely normal. I'm just not sure the solution is to become a hobo.

We're often challenged by our docs. A draft review comes back, and it ain't pretty. That doesn't mean we have failed; on the contrary. The only thing worse than a draft full of revisions is a draft with none. Mistakes and omissions are important; from them we grow into better technical communicators.

It's also important to remember that the end user never sees all the changes, heated discussions, endless debates and other nonsense that occurs when a document is being developed. All they see is the final product. They don't know, nor do they care, about how it got there, just that it's good now.

Think about it - do you care about all the errors that were made before you got your hands on a product you were using? Whether it's a TV, a chair or a pair of shoes, all you care about is that the errors were resolved. Especially if you own a Toyota.

So, if work's getting you down, don't quit, and don't move into a hut. Savour the challenges. For when you hammer steel, it becomes harder.
Read More
Posted in news, philosophy | No comments

Tuesday, 2 March 2010

A New Mantra

Posted on 16:10 by Unknown
Apple has given technical communicators a new mantra.

The Apple slogan is: There's an app for that, to market the fact they have an app for everything and then some, for their ubiquitous iPod touch and iPhones.

Our new slogan should be: There's a doc for that, to market the fact that we can create a document for anything.

Driving a car?
There's a doc for that.

Assembling a table?
There's a doc for that.

Launching the space shuttle?
There's a whole bunch of docs for that.
Read More
Posted in technology | No comments
Newer Posts Older Posts Home
Subscribe to: Comments (Atom)

Popular Posts

  • Six Things That Should Be Single Sourced
    Single-sourcing, as we all know, is the art and science of using a single repository of information to produce multiple outputs. Typical ex...
  • Interviewing and Dating: A Single Source Solution
    Last month, people celebrated "Valentine's Day", a day to celebrate romance and love, a day to be extra-nice to your partner, ...
  • The Power of Words
    There's nothing like an election to illustrate how powerful words are. Politicians, pundits, and the media use words to advance their ca...
  • The Governing Dynamics of Documentation
    Game theory is a specialized field of mathematics that analyzes choices and results in strategic situations, or games , as the players try t...
  • Why info systems fail
    If you only have time to read one news article today, read this one from the Financial Post. Don't leave IT to the techies - Three probl...
  • How to update a document - NOT!
    Canadian International Co-operation Minister Bev Oda needs to work on her document management skills. She hand wrote the word 'NOT'...
  • Publishing for Pollard
    Most of you probably have never heard of Jonathan Pollard, the American who has been languishing in prison since November 21, 1985, almost 2...
  • The Dynamic Blogger
    Some of you may have noticed the new look of this blog. It's a new Blogger feature called dynamic views . You can now choose how this bl...
  • Dude, where's my document?
    Try this experiment: Think of a printed guide you worked on. Find the source document from your current location. Make a minor change to the...
  • Security breach!
    It's always entertaining to read about non-lethal lapses in security at a major event. Remember the debacle at the 2010 Winter Olympics?...

Categories

  • art
  • autism
  • bad communication
  • business
  • career
  • cloud computing
  • computers
  • creativity
  • entertainment
  • finance
  • food
  • Google
  • history
  • interviewing
  • math
  • media
  • medicine
  • misc.
  • music
  • nature
  • news
  • philosophy
  • politics
  • quantum theory
  • religion
  • resume
  • resumes
  • science
  • security
  • simplicity
  • sport
  • technology
  • usability

Blog Archive

  • ►  2012 (9)
    • ►  September (1)
    • ►  August (1)
    • ►  July (1)
    • ►  April (2)
    • ►  March (2)
    • ►  February (2)
  • ►  2011 (36)
    • ►  December (2)
    • ►  November (2)
    • ►  October (6)
    • ►  September (2)
    • ►  August (4)
    • ►  July (5)
    • ►  June (3)
    • ►  May (6)
    • ►  April (2)
    • ►  February (3)
    • ►  January (1)
  • ▼  2010 (47)
    • ►  December (3)
    • ►  November (6)
    • ►  October (4)
    • ►  September (2)
    • ►  August (1)
    • ►  July (2)
    • ►  June (2)
    • ►  May (3)
    • ►  April (5)
    • ▼  March (11)
      • A healthy-sized document
      • Size doesn't matter
      • No sex please, I'm neutral
      • When mail merges go bad
      • Blockbusted
      • Security breach!
      • Taxing my docs
      • The Sixth Sense
      • Gold, finally
      • Krazy Karl Rabeder
      • A New Mantra
    • ►  February (7)
    • ►  January (1)
  • ►  2009 (36)
    • ►  December (11)
    • ►  November (5)
    • ►  October (4)
    • ►  September (2)
    • ►  August (2)
    • ►  July (3)
    • ►  May (1)
    • ►  April (3)
    • ►  March (2)
    • ►  January (3)
  • ►  2008 (24)
    • ►  December (9)
    • ►  November (1)
    • ►  October (7)
    • ►  July (1)
    • ►  June (1)
    • ►  May (1)
    • ►  April (1)
    • ►  March (1)
    • ►  February (1)
    • ►  January (1)
  • ►  2007 (10)
    • ►  December (1)
    • ►  November (2)
    • ►  October (4)
    • ►  August (1)
    • ►  March (1)
    • ►  January (1)
  • ►  2006 (4)
    • ►  September (1)
    • ►  June (1)
    • ►  April (1)
    • ►  February (1)
  • ►  2005 (10)
    • ►  December (1)
    • ►  November (1)
    • ►  October (1)
    • ►  September (1)
    • ►  June (1)
    • ►  May (1)
    • ►  April (1)
    • ►  March (1)
    • ►  February (1)
    • ►  January (1)
  • ►  2004 (9)
    • ►  December (1)
    • ►  November (1)
    • ►  September (1)
    • ►  June (1)
    • ►  May (1)
    • ►  April (1)
    • ►  March (1)
    • ►  February (1)
    • ►  January (1)
  • ►  2003 (9)
    • ►  December (1)
    • ►  November (1)
    • ►  September (1)
    • ►  June (1)
    • ►  May (1)
    • ►  March (1)
    • ►  February (1)
    • ►  January (2)
  • ►  2002 (3)
    • ►  December (1)
    • ►  November (1)
    • ►  October (1)
Powered by Blogger.

About Me

Unknown
View my complete profile