A Note on the New Notes

When not wanting to pay cash, we "put it on plastic". In Canada, plastic will soon be the only choice, as our paper bills are replaced by polymer ones.

The new polymer bills, to be rolled out over the next few years, contain a number of security features to inhibit counterfeiting. These features include clear panels, metallic images and hidden numbers that appear when the bill is held up to a light.

Because the bills are made of polymer, they will last longer than paper bills. They should also survive being accidentally washed if you forget to take them out of your pocket, giving new meaning to the term "money laundering".

The Bank of Canada (like all agencies that produce money) plays a constant cat-and-mouse game with counterfeiters. They release new versions of cash, the counterfeiters figure out how to duplicate them, and the cycle continues.

Paradoxically, government agents specializing in spotting counterfeit money don't usually study it. Instead, they intensely study real money, so that when a counterfeit bill appears, the agent can easily spot it.

Counterfeit docs exists in our profession. These may be legitimate documents included in a product, but are nonetheless forgeries because they:

• contain errors
• are missing critical information
• are unclear or difficult to understand

Studying counterfeit documentation will not make you a better writer. It will only teach you how to be a poor one.

Studying legitimate documentation that is well-written, clear, simple, accurate and easy to understand and navigate might.

Read More

How do you like them Apples?

The world recently mourned the death of Steve Jobs, founder of Apple. He has been hailed, quite rightly, as a creative genius, a brilliant and revolutionary designer, and a bold visionary who completely transformed the world of personal technology. (Full disclosure - my first computer was an Apple IIc, way back in 1985. It was also my last.)

As brilliant as Jobs was, he was also stubborn, arrogant, and an extremely demanding perfectionist who was openly abusive towards his employees. In fact, his arrogance and hubris probably killed him. He refused medical treatment for nine months, insisting on treating his cancer with diet, acupuncture, herbal remedies and a psychic. This delay most likely shortened his life.

Jobs was influenced by Buddhism, which explores the connection between mind, body, and soul. Given how cruel he could be to others, and his frequent violent rages, one could say he had a "cancer of the soul". Buddhism suggests that a disease of the soul can morph into a disease of the body. It's a medical fact that some diseases have a psychological basis. Whether this was the case for Jobs, we will never know, for he now resides in the iCloud.

(Speaking of life and death, we now know why Apple devices don't have an on-off switch. Jobs felt that an off switch represented death. It symbolized for him the terrifying prospect that we're all machines that simply "power off" at the end of our lives.)

These observations are not meant to criticize or judge, but to point out that no-one is perfect, and that there is more to a person than their technical abilities.

An Untechnical Communicator
A technical communicator may be a technical genius, like Jobs. They may have extensive experience managing a wide variety of complex documentation, thorough knowledge of all the major tools, and can speak twelve languages, human and computer. But if that person comes across as arrogant, obnoxious, highly critical of others and emotionally unintelligent, they will not succeed at job interviews. Even if they do land a job, they may have a tough time keeping it. Jobs himself was fired from Apple, and it was a long road back for him to regain control.

I've had the misfortune of knowing a few individuals like these. In the end, they either change or they go, or else every who works for them goes!

All of this means that you can win a job in an interview even if you are not the most technically qualified. The truth is that most software apps can be learned in about a week or two. The more difficult skills to acquire are non-technical:

• interviewing and listening
• working well with others
• oral communication/public speaking
• time and project management
• negotiating
• teaching
• planning
• objectivity, seeing the "big picture"
• being open to criticism
• handling change, conflict and stress
• creativity, flexibility and adaptability

If you can show that you have these skills, and a genuine passion for the job, this will greatly increase your chances of getting it.

Research? We don't need no stinkin' research!
It's interesting to note that Apple conducted no market research - no focus groups, no interviewing, no surveys - nothing. They simply designed products that they thought were cool and useful, then unleashed them on the public.

This seems to contradict to one of the tenets of our profession: to actively design with the end user in mind based on their needs and wants. Presumably, this involves working directly with our readers and having them test our documentation to see if it's useful.

The problem is that we often don't have the resources to do this. The good news is that we don't have to, for reasons that are similar to those at Apple.

Users 'R Us
The fact is - we are users. We should have a good idea of the kinds of information our users want, and the way it should be presented.

When you need information, you want it to be clear, understandable, and easy to find and use. That is precisely what our users want.

Jobs believed it was meaningless to ask customers what they wanted because they didn't know what they wanted! This was true because the products Apple created were so different from anything that the users had previously experienced. How could users be asked about something for which they had no form of reference?

In many cases, our customers may not know exactly what information they are looking for. The example I always like to give involves the mail merge process.

That Mail Merge Thingamabob
If you were documenting the mail merge process for a novice user who had never even heard of it, you couldn't simply create a topic called Mail Merging, with a corresponding mail merging index entry. Instead, you'd need to think about all the ways a user could refer to what they want to do, and then frame the topic accordingly.

For example, you might title the topic: Creating Multiple Personalized Copies of Letters and Other Documents or Personalizing a Document that is Sent to Several People. Your index entries could include:

• addressing one document to several people
• copies of one document, customizing
• customizing a document to be sent to several people
• different names, entering on a document for several people
• documents, individually addressing to several people
• mailings, sending customized documents to several people
• mass mailings, performing 
• multiple copies of a document, personalizing for each person
• names, changing each on several copies of one document
• personalizing one document sent to several people
• sending one document to several people
• single documents, changing the name on several copies of
• specifying different names on several copies of one document

You should be able to develop an extensive list of index entries like this without having to ask the user first.

But take great care with each entry - because one bad Apple can ruin the whole bunch.

Read More

I Can C Clearly Now

The following article contains much wisdom:
All I really need to know I learned in kindergarten.

I would this reword to:
All I really need to know about technical communication I learned from the letter C.

C is the first letter of all the important concepts, practices and other things that you'll ever need to know about our profession.

We must, of course, excel at Communication, and not just the written kind. We must be excellent visual communicators, with a firm eye for the design and layout of images, diagrams, and text. This includes a good knowledge of typography, graphics, and effective diagramming - for example, formatting screen shots so that each part is clearly identified. We must be effective and Competent informational Craftspeople, taking great Care in every word we write.

We must strive for Clarity in our work. This means being Childlike, with an endless Capacity to ask foolish questions, and thereby obtain the answers our readers Crave.

Clarity includes being Comprehensible. If our readers (or Clients) cannot understand what we've written, why did we write it? We must therefore be Customer-focused. Ideally, we should observe our readers attempting to use our documents. At a minimum, we should provide a simple way for them to directly send us their Comments and Criticisms. This involves having Compassion for our readers. They are often stressed when they reach out to our guides. Our job, therefore, is to Care about our readers and create documents that gently guide them onto the right path.

The Content we develop must be Complete and Comprehensive. A document is a puzzle, but one in which you may not know the number of pieces. Knowing that you don't know what you don't know is the first step in knowing what you need to know, you know?

At the same time, our documents must be Concise. We should use as many words as required, but no more. We can achieve this balance through the Chunking of information. For example, we can create a simple overview page that contains links to various topics, rather than listing the entire contents of all these topics on one page.

Organizing and chunking the information involves Curating, the active management of all our informational objects. A museum curator decides what pieces should be displayed, where and how; we must do the same.

As we curate our information sets, we must be Cost-Conscious. This involves effective time and project management as we juggle all our guides. It also involves Content reuse at the topic, paragraph, sentence and even word level. Common copyright information, procedures and tasks, and templates are just some of the things that should only exist in one place. This will lead to greater Consistency in all our documents.

Consistency is extremely important. You should not call the same thing by different names, nor describing different things using the same.

Our documents must be Credible (or believable). If there is an error in a document, its credibility is destroyed. Also, we must be credible. Others must believe what we say when we give our advice on content and design and trust that what we say is true - this relates to Confidence.

As you grow in your career, your confidence grows. A junior writer asks others: What should I do? A senior writer is asked by others: What should I do? The difference between the two is confidence, which comes with experience.

Confidence enables you to deal with Conflict, of which there is no shortage of in the business world. When two SMEs disagree on the contents of your document, it is a conflict that you will have to work to resolve with them.

Confidence also enables you to deal with Change. Change happens on so many levels - in people, in companies, and of course, in our documents and the way they get created. Accepting and managing this change is a critical skill to have, and requires Courage. I remember a tumultuous time when, as a result of various mergers, the company I worked for changed about every year. It was a stressful time, but also exciting, as everyone worked to manage the change.

Of all the C-skills to have, Creativity is the most important, because it encompasses all these other ideas. People who win at job interviews do so because they show how they have creatively solved documentation problems. Both your resume and in your interview should overflow with samples of your creative genius. It's great that you know FrameMaker, but so do hundreds of other people. Instead, focus on how you improved the documentation and the documentation process in a creative way.

Creativity also involves working Colloboratively with others. We tech writers are an introverted lot, a habit we need to break. No person is a cubicle. The more we interact with other writers and non-writers, the better. Have you ever stopped and asked a code developer what they do? What they like? What they think of your documents?

Practicing all these skills enhances your Career. Career management is a whole other discussion. Managing your career and network of Contacts is like tending a garden. It takes time and care, but the end results are worth it. I owe my current job to the contacts I had carefully maintained.

Now, there is one C-word that is not a skill, but a shape: Circle. The letter C is like a circle with a gap:

C

The gap is symbolic of the gap that is present in all documentation: the gap between what the reader needs to know and what is actually in the document.

Salespeople have a saying: A.B.C.: Always Be Closing. Whenever they interact with clients, their entire manner and tone assumes the sale has been made - they just need to "Close" it.

Technical communicators need to practice A.B.C. We must come full circle and close the gap. Because when it comes to us and our readers...

...we are all Connected.

Read More

reCAPTCHA'd!

reCAPTCHA is an excellent example of not only solving an informational processing problem in a creative way, but in solving the original problem, also solving a much larger one.

Before you can understand reCAPTCHA, you must first understand its predecessor: CAPTCHA. CAPTCHA was created to solve the problem of automated programs (or "bots") from logging into websites and thereby generating spam in the form of emails and mass postings.

A CAPTCHA screen displays a distorted image of letters or words. A person can read the letters, but a bot cannot. The user must enter the letters correctly to gain access to the system, for example, to sign up for an email account.

This technology alone is a great example of a creative solution to a complex problem. But reCAPTCHA takes it a step further by solving an even bigger problem.

This larger problem involves an ancient form of communication - the printed page. There are tens of thousands of books and newspapers that Google is trying to convert to digital text. Scanning the publications, then using OCR (optical character recognition) to convert the scanned image to text has its limits. If the text is distorted (as it is in many of the older publications), it cannot convert the text.

How does this relate to CAPTCHA? Well, about 200 million CAPTCHAs are done by people every day. If each CAPTCHA takes ten seconds, this effort represents about 63 person years of work every day.

Wouldn't it be amazing if there was a way to put all this time to good use? That is exactly what reCAPTCHA does.

Here's how it reCAPTCHA works:

1. When a document is scanned, it detects a word that it cannot convert. Let's call this the "unknown word".
2. The reCAPTCHA process sends this unknown word as a CAPTCHA for people to deciphere.
3. The CAPTCHA contains not only the "unknown word", but another word which the system already knows. We'll call this the "known word".
4. In the CATPCHA that is created, the user is asked to read both words and enter them.
5. If the user solves the known word, the system assumes that their answer will be correct for the unknown word.
6. The system also gives the unknown word to a few other people to verify that the original answer was correct.
7. If enough people agree on what the unknown word is, the information is set back to the original system and the converted word is added to the document that is being digitized.
8. This process is repeated until all the words in the document are converted.

Can you even begin to imagine the flash of genius that occurred in the mind of the Luis von Ahn, the creator of the reCAPTCHA process?

The problem is that these type of "eureka" moments are very difficult to create. They often just happen, much like the weather. You can no more force yourself to be creative that you can force yourself to love, hate, forget something, fall asleep or go back in time.

However, you can sometimes find creative solutions if you just stop what you're doing, and ask yourself some questions, such as:

1. Is there a better way to present this information to the end user?
2. What else would a user need to know about this concept, task, or thing?
3. How does the user use our documents?
4. What changes could be made to enhance the documentation development process?

I'll give some examples of real-life creative solutions that I've encountered:

Example 1: Our help files have to be checked into a version control system. Each help project can contain hundreds of individual files, and these files are often created, deleted, moved and renamed. It would have been very cumbersome to keep track of each file that was checked in and out. The solution (from a colleague of mine) was this: instead of checking in and out the various files, a zip file of the entire help system was created and checked in instead. The installation program then decompresses this zip file. Only one file now needs to be sent and tracked in the build.

Example 2: I was working with a developer on a complex database administration application. One of the functions the user could do was rerun a query by clicking a button labeled, appropriately enough, Rerun query. The developer said the problem was that there were many different queries that the user could run, and that they needed a quick way to know which one they had run before re-running it. I asked if was possible to embed the name of the query that had just run into the button name, so that, for example, if the user had run the Last Name query, the button label would be Rerun Last Name query? I still remember the developer's eyes widening and his face lighting up as recognized the elegant beauty of this solution. "Yes," he said, "it can be done!" 

Example 3: Many of our help projects share content, templates, and other settings. I wanted to develop a simple content management system that would allow all the writers to share these things across many locations. I created a master help project that contained all the common content and settings. I then linked my other help projects to this master project, so that if any of the common material changed, it would automatically be updated in the other help projects. Finally, I stored all the documentation on a version control system that could be accessed by any writer. As long as each writer has the current version of the master help project and links their other help projects to it, this will ensure the templates and content remained standard.

So don't just think "outside the box".

Ask yourself if you even need the box in the first place.

Read More

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 blog is displayed simply by clicking a link near the top: Classic, Flipcard, Magazine, and so on.

The results are quite spectacular - the listings are display in an animated fashion. No more boring, static text.

This new feature reflects the epitome of effective design in two ways:

• to enable this feature, the author simply has to change one setting - an extremely simple act
• it allows the reader to have control over the display of information

This last point cannot be emphasized enough. We laugh about the days when Henry Ford said that customers could have any colour car they wanted, as long as it was black. We then proceed to create single versions of our documents in which the user is just as unable to change the appearance as they were with the black Model T Ford.

Information can be viewed in so many places: paper, websites, PDAs, tablets, and so on. If that weren't enough, everyone has their own personal preference on how that information is displayed. The ability to give the user some control over that appearance is paramount.

Blogger's dynamic views currently has seven options. Expect to see that number rise to...infinity.

Read More

The Art of the White Night

I recently experienced my first Nuit Blanche, an annual all-night outdoor contemporary art event held throughout downtown Toronto. The event featured a wide of variety of strange and exotic exhibits.

The Heart Machine consisted of four giant steel "arteries" each connected to sensors that when touched the correct way caused giant flames to shoot up, warming the frozen crowd. Flightpath Toronto, held at City Hall, showcased a spectacular outdoor laser show, while people flew overhead on a cable line.

My favourite exhibit was Soon. Held in a large, open outdoor office courtyard, it was the most spectacular work of art I had ever experienced. Searchlights mounted atop office buildings continually scanned the crowds while smoke spewed everywhere. Sounds of helicopters, along with a strange, other-wordly noise, blasted from speakers. The effect was surreal - you were trapped in a bizarre, futuristic totalitarian state.

Almost all the exhibits relied on modern technology: computers, large screen projectors, lasers, and cutting-edge sound and light systems. Without this technology, these exhibits would not be possible. Therefore, technology directly influences and is used by modern artists.

Art (non-technical) communication is therefore influenced by current technologies. Technical (non-artistic) communication is no different. User guides are written in the language of the technology of the day. We have progressed from writing on walls, to writing on paper, to printing on paper, to computers, PDAs, smart phones and beyond. However, the goal remains the same: clear and concise communication.

For both artistic and technical communication, the medium is more than the message - the message and the medium are inextricably linked and blurred beyond recognition.

This blurring occurs in other ways. One of the non-official exhibits was The Red Dot. The theme was inspired by the practice in art shows of placing a small red dot on the descriptive tags next to paintings that have sold. Various sculptures made of red dots were on display, but in addition, large red dots were affixed to various items throughout the area: buildings, trees, doors, cars, and even people. The idea was that "art is everywhere". The intent was to blur the line between art and the so-called "real world".

The effect was rather exhilarating. As my friend and I walked the streets, I began wondering what was real and what was art. At one point in the evening, I saw paramedics help out an ill person. Later, I witnessed a skirmish where several policemen forcibly held down someone resisting arrest. But were these real events, or were they staged? For a split-second, it was difficult to know. When anything can become art, art becomes anything.

Although there is an "art" to documentation, documentation is not art. However, documentation, like art, can exist anywhere. With the liberation of information through the Internet, any one can become a technical writer through blogs, feedback on corporate websites, forums and any other online area where information likes to gather.

This blog attempts to be a hybrid of both art and technical communication. My hope is that it teaches you how to be a better technical communicator, but I consider it creative (non-technical) writing. Which means it blurs the line between art and reality. Which means that any at time, I could





[Blogger server error 2352 - the remainder of this blog entry cannot be displayed*]



*or can it?

Read More