Paying some interest to your docs

With the release of the Ontario and the federal Canadian budgets, debts and interest rates are again in the news. Both budgets continue to run deficits; this is especially frustrating in Ontario, whose government recently commissioned a document (the Drummond report) that recommended major spending cuts; yet another effective user guide that has been promptly ignored.

Interest rates are the lowest they’ve even been in years. This keeps borrowing costs low, but creates another problem: if rates rise even a small amount (as they inevitably will), borrowing costs increase tremendously.

Canada’s debt is currently about $566 billion. Even a tiny .1% rise in interest rates (that’s one-tenth of one percent) would increase borrowing costs a staggering $566 million a year, or over a one and half million dollars per day.

Interest rates are also important on a personal level. For example, if you have a $375,000 mortgage, a 1% rise in rates adds about another $3,750 a year in interest, or over $300 per month. If you’re already treading water and living paycheque to paycheque, this could be enough to push you into bankruptcy, and out of your house – exactly what’s been happening in the United States.

We see then, that the following formula is life-altering:

debt X interest rate = interest payment

Even a small change in rates can greatly increase the interest payment, if the debt is large.

All this got me wondering: What is the interest payment of a document?

To find this out, we need to determine:

  • the debt of a document
  • the interest rate of a document

The debt of a document, like financial debt, represents the total value of the document. This is comprised of the size of the document, including the total number of words, graphics, index entries, cross-references and other information elements.

The interest rate of a document includes:

  • the volatility of the document – the degree to which the document needs to be updated because of changes in the product or thing being document; in other words, how much and how frequently the document must be maintained
  • the importance of the document – a document that is not used or is considered irrelevant or unimportant has little value; the users or the organization that owns the document literally has little interest in it

A document’s interest payment is the amount of effort a technical communicator must exert to ensure that the document is properly maintained. It is the size of the document multiplied by its interest rate.

Larger documents generally have higher interest payments than smaller ones, because greater effort is required to maintain them. However, a large document may have a lower interest payment if its interest rate is sufficiently low, for example:

Large document: 5,000 x 1% = 50
Small document: 3,000 x 2% = 60

The first figure in each equation (the debt or size of the document) is arbitrary and is simply there to indicate relative sizes.

Now, what happens if you fail to make the interest payments? The debt of the document increases as it becomes more outdated and chaotic. It may even reach a point where the owner must declare bankruptcy and create an entirely new document.

Who knew documentation could be so…interesting?

Advertisements

Single Sourcing Greece’s Default

Related imageGreece is now dangerously close to defaulting on its national debt. Despite the recent bailouts, many financial experts believe that the situation is unsustainable. Greece simply cannot afford to pay its bills. Its debt to GDP ratio is a staggering 140%, meaning it owes almost one and half times the value of all its goods and services. It could only be a matter of time before Greece defaults.

Defaulting, while certainly undesirable, does not necessarily mean the end of a country. Argentina, Russia, Ukraine and many other countries have also defaulted, and have gone on to have healthy and vibrant economies.

Still, the European Union is desperate to save Greece from default because they believe that if Greece defaults, it could plunge the entire region into financial chaos and destroy the value of the euro. Therefore, you could say that the decision to unite the currencies of Europe caused this problem in the first place. If Greece had never joined the euro, they still would be in a mess, but it would have been their own mess.

Single-sourcing in technical communication refers to the process of storing a piece of information once and then reusing it as needed. The euro is a political and economic example of single-sourcing. Seventeen different European nations use it, instead of maintaining separate currencies.

When the euro was first introduced, Europeans were hopeful that by single-sourcing their currencies, they would eliminate the disadvantages of multiple currencies, namely the inefficiencies of currency conversion. But as we’ve now seen, these advantages have been decimated by the Greek fiasco, costing billions of euros to fix.

It is very easy to make the object to be single-sourced too large. For example, you may have a complex procedure containing ten steps that appears in three separate guides. As long as the procedure does not vary, there is no problem. However, what if later you need add a new step to only one of the guides? You could add the step and then conditionalize it so that it is hidden in some of the guides but appears in the necessary guides.

But what if later the situation becomes even more complex? What if you need to hide or add certain steps to certain guides? By choosing to single source the entire procedure, you have essentially backed yourself into a corner, much like Europe with Greece.

The only effective long-term solution is to store each step as a separate object, then assemble each step in each document as needed. This gives you the full flexibility to include or omit steps as needed.

In essence, you need to “default” on your original documentation architecture, declare informational bankruptcy, restructure and begin anew.

To choose not to would be a Greek tragedy.

iHate unclear product names

1Apple finally launched its latest iPad. Because it comes after the iPad 2, most everyone expected it to be named the iPad 3, following the naming conventions of the iPhone. Instead, Apple gave it a name that only a marketer could have developed:

The New iPad

If a technical communicator had been asked to name this product, this name would never have entered their mind.

Where to start?

First, how long is this iPad going to be new? One month? Three months? Six months? Major product releases are often a year apart or more. Can you imagine walking into an Apple store a year from now and asking for a “New iPad”? I guess some things have more “new” than others.

Next, what will they call this iPad once the next one is released, assuming it will still be for sale? The Not So New iPad? The iPad Between the New iPad and the Even Newer iPad?

Finally, the iPad 2 is still available, at a reduced price. I can just picture the conversation:

MacHead 1: Hey, I just bought a new iPad!

MacHead 2: You mean the new iPad?

MacHead 1: No, silly, I mean a new iPad 2!

MacHead 2:  So it’s not a new iPad?

MacHead 1: It is a new iPad, it’s just not the new iPad. Geez…what’s so hard to understand?

Why can’t companies stick with clear, self-descriptive names? I admit the traditional naming sequence is boring: Product name 1, Product name 2, Product name 3, and so on. But at least it’s comprehensible.

Maybe I’m being picky. Maybe, like the old Apple slogan use to say, I need to “think different”. To that end, here are my suggested names for the next iPad:

  • The Newerest iPad
  • The Much More Newer iPad
  • The Newer iPad That’s Way Newer Than The New iPad
  • The iPad with New All Over It
  • The Supercalifragilisticexpialidocious iPad, Now With Even More New!

Or maybe we could combine both the marketing approach and the clear communication approach:

  • The iPad 4 – “Who New?”

Apple. Think different. Name stupidly.

A Technical Communication Occupation

The Occupy Movement hurtles towards its expected demise. With the Occupiers (a.k.a. urban campers) now evicted from their various parks, this movement is headed the way of the hippies. As New York City mayor Bloomberg eloquently stated: “Protesters have had two months to occupy the park with tents and sleeping bags. Now they will have to occupy the space with the power of their arguments.” What they shall they do to occupy their time?

Has the Occupy movement had any effect? As the Premier of China said when asked in the 1970s about the effect of the French Revolution 100 years prior: “It is too soon to tell.”

Still, there’s lessons to be learned from this movement for technical communicators:

Lesson #1: No leader, no way

Without a leader, a group cannot succeed. The Occupy movement prided itself on having no leader, thereby laboriously deciding everything by committee. Everyone was a leader, so no one was leading. A group with no leader has no future, because there is no one with the vision, authority and responsibility to move the group toward its goals.

That is why every documentation team must have a leader, someone who can guide, enhance and develop the group. With no leader, there is no place for the group to go but off into the various directions each communicator wants to take it. With no leader, there is no way.

Lesson #2: Pursue clarity

The Occupiers had too many demands, and the ones they had were vague, among others: a redistribution of wealth, the restructuring or elimination of capitalism, world peace, a change in the system of government, and protecting the environment. Exactly what the protestors thought each of these entailed and exactly how they were to be implemented is not clear.

Clarity is the essence of effective technical communication. If your documentation is not clear, then you are not clear. If you cannot explain to a stranger a topic you have written, then you are a stranger to clarity.

Go clear, or, like the occupiers, go home.

Lesson #3: Ask Hard Questions

When evaluating news stories such as this, we must do what technical communicators do best: ask what the real, practical effects are.

Regarding the recent evictions, there were only two possibilities before they occurred:

  1. The occupiers would all be evicted, destroying or least severely weakening the movement. Without a physical presence, there is no mental presence. This is exactly what is happening.
  2. The occupiers would be allowed to stay. If this had happened, then the worst thing that could have happened to the movement would have happened: the public would have become used to it. When people get use to something, they forget it, until the NBT (Next Big Thing) comes along.

Now, when evaluating the contents of the document and the document management process, we must ask the same hard questions:

  • Does this make sense?
  • What is the practical value here?
  • What are the logical outcomes of the various choices we can make?

 When evaluating the contents of a document, we ask:

  • What does this contribute to others?
  • Is there a better way to express this?
  • What is missing here?
  • Is anyone really going to care about this?

Similar tough questions need to be asked when looking at the process by which the documentation is created, reviewed, updated and managed:

  • Is there a better way?
  • How can we manage this document more effectively?
  • What are our options, and what is the potential outcome of each?

Companies often fall into a trap of producing poor documents or having poor documentation processes. Their response is often: “That’s how we’ve always done it,” to which our response should be: “Well then, you have always done it wrong.” Another excuse is: “That’s how other groups do it,” to which we respond: “Those other groups are also wrong.”

To effect change, you need to have COP: Creativity, Objectivity, and Perseverance. Specifically, the only way to bring about change in a document or the documentation development process is to be (in this order):

  • ruthlessly objective of the current state
  • incredibly creative when offering the solution
  • mercilessly persistent in actually fixing it

About one in a hundred technical communicators have these three traits.

Are you one of the 1%?

A Note on the New Notes

Related imageWhen 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.

How do you like them Apples?

Image result for Steve Jobs logo

The world is mourning 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.

Shaken

See the source imageIt’s not every day that you get to experience an earthquake, and I’ve had the misfortune of experiencing two, both times in the building I work. The last one, with an epicenter in Virginia, shook our entire floor for several seconds.

At first I thought we were expendable employees since no one came around to evacuate our floor. It turns out that remaining in the building was the safest action, as most injuries are caused by falling debris when leaving a building. Many workers were therefore wrongly evacuated from their workplaces. People need to re-read the “disaster” chapter of their office safety guides.

Thankfully, this last earthquake caused minimal damage and no deaths, but many others have been terrible killers. The 2010 Haitian earthquake killed over 300,000 people. The world record goes to China, where an earthquake in 1556 claimed a staggering 830,000 lives.

Note that earthquakes don’t actually kill people – the collapsing buildings do. This explains why there were so many deaths in Haiti, because many of the buildings were very poorly built, since Haiti itself is very poor.

Buildings simply aren’t natural – they are man-made. When you combine the natural with the unnatural, you naturally run into problems. Earthquakes occurring in non-developed areas do not wreak the same level of destruction as in developed areas. Mountains and trees, being part of nature, usually remain intact.

One way to build safer buildings, therefore, is to look to nature. Just as most trees sway but don’t collapse in a quake, newer buildings are designed to sway when the ground shakes. By emulating nature rather than fighting it, lives are saved.

It requires a great deal of money, time, testing and study to copy nature. This is a general principle of all design. Making the unnatural natural does not come naturally, or cheap. Software that converts spoken words to text is a good example. Great strides have been made in speech-to-text applications, but they are still not 100% correct.

A more extreme example is replacement limbs. Even today, it is difficult to create artificial limbs that have the same look and feel of the original parts. It is the supreme challenge to make the logical biological. The day may come when a replacement arm feels no different than the arm it replaces – I would give my right arm to be the inventor.

Technical communication also attempts to make the unnatural natural. It is the process of helping a person interact with something unnatural (a man-made product, service or thing) using something unnatural (a man-made document) in such a way that they can understand and use this manufactured thing in a natural way.

Therefore, the hardest things for a technical communicator to do are:

  • describe something using natural language in a way that a user can easily understand
  • encapsulate and package this information within a form that a user can use with minimal effort

Documentation should be like a glass bowl displaying only its pure contents. If the user can “see” your document, it blocks the view of the contents, frustrating the user. Similarly, if the user has to struggle to find or understand the relevant information, then the guide becomes unnatural, and is no longer a guide, but a wall.

The most well-design documents don’t appear designed – they simply work in a way that does not conflict with the human user. Now, it would certainly be easier to design documentation if we were all robots, but then our jobs wouldn’t be as fun, would they?

Technical communication, therefore, is the process of making the unnatural natural. A successful document is one that makes the understanding and use of a product, quite literally, “second nature”.

33

Related imageWhat a great day to be Chilean.

It’s certainly true that the 33 miners rescued from the depths of the earth are heroes. Anyone who can survive over two months trapped in that pit of hell must be considered nothing less.

But as CBC’s National Science Commentator Bob McDonald pointed out, the other heroes are the engineers who designed the miraculous escape capsule which pulled all the trapped men to safety, with no major problems, and ahead of schedule.

We are all engineers; engineers of communication.

May all your engineering projects end as beautifully as the one in Chile.

Censoring the census

Related imageIt’s a slow month in politics when the current burning issue for the Canadian government is a form document that no-one enjoys completing.

The government is in trouble because of their plans to scrap the mandatory 40-page long version of the census. It would be replaced by a shorter, voluntary version. Opposition parties, statisticians, researchers, and other groups say this will result in unreliable data being collected.

The government argues it’s wrong to threaten fines and jail time for failing to fill out the census, and that the long form was too intrusive, with too many personal questions.

The government has a point. Look at some of the information required in the long form census:

  • the languages you speak at home
  • your race, nationality, and religion
  • where you work and how get there
  • the language you use on the job
  • how much housework you do
  • how much time you spend playing with your kids or talking to your parents
  • whether you have trouble walking, climbing stairs, or bending
  • who pays the rent or mortgage
  • how many rooms and bathrooms in your home
  • whether your home has any “missing or loose floor tiles,” “defective steps” or more major deficiencies like “defective plumbing”

Does the government really need all this information? Although it’s important for governments to plan for the future, I doubt all these excessive, personal details are really required. But that’s not my main complaint.

The real problem is that I don’t see why this document (either the long or short version) is even needed.

The entire system of mailing out a paper document to millions of people, having them mail it back, then having thousands of workers manually place the completed forms into a machine that can read them is nonsense.

I’m not suggesting that all this information should just be entered online. Aside from the fact that this assumes everyone has Internet access, this would still be a flawed process because:

  • it requires people to complete a form, which introduces errors
  • the data is only entered every few years, meaning it is never up-to-date

The real solution would be to glean the information on a continual basis in real-time from existing government databases. Everyone in Canada already has an ID number: a SIN, or Social Insurance Number. This number already contains much information about you. The government could use this information on a continual basis, in both short and long term planning.

Such a system would actively pull the required information, without forcing citizens to enter it, and would always be current. Yes, it would be an invasion of privacy, but so is the census itself. If you’re going to invade everyone’s privacy, you might as well do it cheaply and efficiently.

If the government ever created a system, they would simply be following the best practices of modern information management systems. In these systems, manuals are not just issued every few months when there is a release. They are continually updated, regenerated and then posted online. This allows the end user to always have access to the most current version.

It’s time to move all paper-based forms to the ash heap of history where they belong.

Census designers – I hate those guys…

Join the Bloc!

Related imageI survived the G20 riots. They happened near my former workplace in downtown Toronto; fortunately, our office had recently moved to the slightly more peaceful city of Markham. No one was surprised by the violence; it was all foreseen, based on the history of previous summits. Remember the “Battle in Seattle” in 1999? It’ll be difficult to name this current event, as there are few words that rhyme nicely with Toronto. Perhaps “The Scenario in Ontario”.

What exactly did the G20 summit produce? A non-binding document, in which, among other things, the various leaders pledge to reduce their outrageous spending. What happens to leaders who don’t meet their deficit reduction targets? Well, the other leaders might stare really, really hard at them, call them names, and maybe even start turning the lights on and off. Oh boy – that’ll scare them into fiscal responsibility.

Time for some post-mortem documentation analysis. The security costs alone for the summit were over a billion dollars. There are 10,500 words in the released communiqué. That works out to over $95,000 per word. However, the total cost is even higher when you factor:

  • transportation, food and housing for all 10,000 delegates
  • construction of all the venues, including the “fake lake”
  • the funky G20 logos and marketing
  • three slightly over-cooked police cars
  • damages to stores
  • lost business
  • court costs for the anarchists

When all these are added in, the cost per word easily exceeds $100,000, a handsome rate for any writer.

Here’s a few other random thoughts from this event:

Don’t want to be arrested? Read the manual!
Over 900 people were arrested during the summit – a new Toronto record – woo-hoo! Now, some of those arrested and detained were admittedly innocent; passers-by, onlookers and journalists. To avoid future errors, I recommend a Summit Safety Manual be issued to all residents of the next city fortunate enough to host the next G20 summit.

This manual will contain only one procedure:

Not Getting Arrested
 
If you do not wish to be unavoidably detained and arrested, and held for an unlimited number of hours without access to food, water and washroom facilities, please complete the following task:
  • Stay far away.

Sign, Sign, Everywhere A Sign
I enjoy reading the communication (a.k.a. signs) displayed by the protesters with such brilliant and pithy statements as:

  • Ban the G20!
  • Capitalism sucks!
  • Bury the bankers!
  • Nature doesn’t do bailouts!

The problem is that unlike a well-written document, the signs don’t tell the reader what to do. I therefore plan to show up at the next protest with the following sign:

  • Ensure your sign includes a clear, specific action for the reader!

Even if the signs had been clearer, as documents they are useless. The world leaders are the end users for these signs. Has there ever been an instance where these leaders have said: “Gee, this sign says ‘Ban the G20’. I guess we’d better cancel the meeting.” Clearly, the sign-writers have yet to learn the prime directive of technical communication: Know your audience.

A Paradox for Anarchists – Let’s Get Organized!
To call the anarchists who destroyed property idiots would be an insult to idiots everywhere. These thugs have the intelligence of blank hard drive. Now, there’s nothing wrong with a little bit of revolution now and then; many great nation-states were born from revolution. The difference, of course, is that these historical revolutionaries stood for something, whereas the anarchists stand for nothing, except, of course, more anarchy.

Technical communication is undergoing a revolution from:

  • traditional WYISWYG tools where the content and the design of information is done simultaneously, and the documents are typically stored locally and organized into chapters and books

to:

  • server-based XML tools where the author works only with segments of pure text (no formatting), which are classified based on their type and which are stored on a central server that many authors can access

This is a colossal change; I am therefore launching a new movement named after the infamous Black Bloc G20 anarchists – it will be called The Text Bloc.

Join us as we smash old (computer) windows and destroy the old outdated documentation ways!

Chant with me now the following statements:

  • Death to WYISWYG! (Or at least partial harm to it!)
  • Paper-based systems don’t do bailouts (and they don’t do many other things either!)
  • Hey Mr. C.E.O. – can you spell X.M.L?!
  • Information wants to be free! (But avoid anthropomorphization!)