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

Greece 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.

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%?

Remove bomb; replace with cupcake

Informational high-tech agents (a.k.a. “hackers”) working for British intelligence broke into an al-Qaeda website and replaced one of the site’s documents.

When end users tried to download a 67-page instruction guide entitled “Make a bomb in the kitchen of your mom”, they instead got a page of – wait for it – cupcake recipes.

“It’s a good thing,” as Martha Stewart would say, since cupcakes tend to be less lethal than bombs.

And who said informational workers don’t kick ass?

Terrorists. I hate those guys.

Lessons from the 2011 Canadian Election

The results of Canada’s recent federal election were truly stunning. If you’re not Canadian (or are but have been living under a rock), here are the results:

  • the Conservatives won a majority of the districts (or seats), capturing 167, up from 143
  • for the first time ever, the NDP formed the official opposition by winning 102 seats, up from 37
  • the Liberal party was reduced to third place, winning only 34 seats, down from 77
  • the separatist Bloc party in Quebec was reduced to “junk bond” status, down from 49 seats to only 4, out of 75 seats in that province

What can technical communicators learn from all this?

Let the learning begin…

Lesson #1: Stability and change can co-exist

The election results were paradoxical to say the least. Only 40% of Canadians voted for the ruling Conservative party. However, voters also left the Liberal party in droves, elected more NDP MPs than ever, and dumped the ruling Bloc party in Quebec.

Did voters vote for change or for more of the same? They did both. Due to the peculiar nature of our first-past-the-post voting system, the Conservatives gained only 2% in the popular vote, but 17% more seats, more than enough to obtain a majority. At the same time, the NDP gained 13% in the popular vote, but increased their seat count a staggering 175%. The numbers don’t lie, but they sure tell a funny story.

Existing documentation projects, as well as software, share a similar paradoxical quality. They must be stable enough so that current users can continue to use them without getting lost or confused. At the same time, documentation is constantly evolving as the product changes and the documents are updated.

Striking the right balance between stability and change is one of the great challenges of our profession. That’s why is often liberating to work on new projects, but even then, they often need to be developed within existing standards. 

Lesson #2: Sometimes less is more

NDP leader Jack Layton gained more seats and is now the official opposition party. It may seem the NDP gained more power, but strangely, they may have even less. This is because previously the NDP was one of three parties that held the balance of power. The NDP could and did threaten to join with the other parties to bring down the government. Under the current Conservative majority government, the NDP have lost that power. That is, they won, but they also lost, showing that less is sometimes more.

“Less is more” is one of the axioms of our profession. Shorter, concise paragraphs and topics are much more powerful and effective than longer ones. In other words, “when in doubt, leave it out.

Lesson #3: Hubris is death

As described previously, the leaders of the Liberal and Bloc parties joined forces with the NDP to bring down the government and force an election. Bloc leader Gilles Duceppe believed he would continue his winning streak in Quebec. Liberal leader Michael Ignatieff hoped to become the next Prime Minister, or, at the very least, increase his party’s seat count. Each of them conveniently provided the noose around which to hang their own neck.

Not only were the seat counts drastically reduced for these two parties, both leaders lost in their own riding. They had no choice but to resign, leaving each of their parties in tatters.

If there’s one thing the public cannot tolerate, it is the politician who gives even the slightest impression that they are “owed” a victory. Arrogance, hubris, and a sense of entitlement are all a death sentence in politics.

Political campaigns are one long job interview, where each leader tries to convince you to “hire” them through your vote. Hubris is the last quality you want to exhibit in an interview. You need to strike the right balance between confidence and humility. You want to show that you know your stuff, but are not a “know it all”.

In addition, technical communicators are often called on to be user advocates. We push for simplicity, clarity, and consistency, not just in our documentation but in the products and services we document. However, we must realize we do not own these products: the product managers and others who work directly with the end user do. We can advise, but we cannot dictate, for that is the essence of hubris.

Lesson #4: “Top” and “bottom” are interchangeable

The Conservatives are now on top; the Liberals on the bottom. This is not a permanent arrangement. Unless you are living in a one-party state, the ruling party never stays in power indefinitely. As high as the winning party is now is exactly how high the losing party will eventually be. Top and bottom are but temporary states.

Now, if you have made the transition from a traditional, book-based authoring environment to a topic-based one, this principle becomes apparent. Instead of creating pages, chapters and books, you create individual topics that can stand on their own. You assemble and organize these topics into logical groups, such as the TOC folders within an online help system. You can easily move these topics around, quickly relocating them from the top of a document to the bottom, or anywhere else. Again, top and bottom are but temporary states. 

Lesson #5: Take your time

The Liberals now have about four years to rebuild their party. They should use the time wisely, and not rush, otherwise they will never recover. A “sub-lesson” to this lesson is that those who do not remember the mistakes of the past are condemned to repeat it.

For any document or documentation process, especially if it is new, take your time. It’s a cliché to say, but most people don’t plan to fail – they fail to plan. More documentation projects fail or are much more difficult than they need to be because no-one took the time to stop and carefully analyze the requirements and implementation process. They just dove right and started developing content, without first deciding how the content would be used or identifying who would actually be reading it.

I often hear the refrain “we don’t have time to do that”. I would counter that you don’t have time not to. The Liberals have all the time in the world – do you envy them? 

Lesson #6: Branding is everything

The final and most important lesson from the election is the importance of branding.

A brand is the idea or image of a product or service that people can connect with. Branding is the communication of this idea (through marketing) so that it is perceived as being uniquely recognizable from other products or services.

When we think of brands, we typically think of large companies such as Coca Cola, Microsoft, Dell, IBM, and Toyota. However, brands can be applied to anything – even you. (We’ll get to that in a minute.)

Political parties know the importance of branding. To put it mildly, the Liberal brand has been suffering for the last few years. Their continued drop in popularity and seat count was inevitable, no matter who was leading the party. The Bloc’s brand was associated with sovereignty – a concept that most Quebeckers seem to have rejected for now with their embrace of the federalist NDP.

The NDP’s branding, especially in Quebec, was simple and brilliant. One of their Quebec TV ads had dogs barking at each other, with the tag line: “Always the same debates that lead nowhere”, followed by “It’s time for a change. Work together.” This branding was so powerful it catapulted the NDP from one seat in Quebec to 58. Some of the new MPs were university students, including a nineteen year-old voting for the first time in his life. Another student did not even live in the riding she was running for, and was on vacation for part of the campaign. It did not matter; such is the power of branding.

Think that branding doesn’t apply to you? Think again. When you have a job interview, and even after you’ve been hired, you are a brand. You must demonstrate and transmit the key qualities that define you as a technical communicator, and a person. These could include: outstanding communication skills, efficiency, patience, knowledge, technical expertise, a team player, and above all, an improver. In an interview, you must clearly show in your work experience that you are passionate about your profession and have actively enhanced the quality of the documentation and the documentation process. That is your brand – your brand is you.

These are the lessons from the election. There are many others. Anyone who wants to discover these has my vote.

Name that document

I saw a document on the news today with two entries, each followed by a number.

It’s not a TOC.

It’s not an index, either.

It was a hand-made sign summarizing yesterday’s historic event: the irreversible deletion of one (1) Mr. Bin Laden:

OBAMA: 1
OSAMA: 0

I couldn’t have documented it better myself.

Failsafe

President Obama recently proposed an intriguing solution to deal with his country’s ever-growing debt: a “failsafe” trigger. Here’s roughly how it would work: if the debt as a share of the economy (the debt-to-GDP ratio) does not drop below a certain ratio by a certain date, then spending cuts, tax increases, or both would automatically be implemented.

Politically, it’s a brilliant solution, as it transfer the onus of decision-making from the politicians to the bureaucrats, as they are forced to make the deep but necessary cuts to lower the debt, currently a nightmarish $14 trillion.

A failsafe system can be applied to any process. It is comprised of:

  1. a specific, measurable goal to be achieved
  2. a date or time period by which the goal must be met
  3. a specific, measurable action that will be taken if the goal is not met

A simple example is weight loss. For example, you could set a goal of losing 3 kg. in two weeks. If you fail to meet this goal, you would have to lower your intake by 300 calories, exercise an additional 30 minutes, or both. You would repeat this failsafe system until you have reached your ideal weight. Then comes the tough part: maintenance. A second failsafe system ensures you stay on track.

Could a failsafe system be developed for documentation? It could, if we can define a measurable goal. However, objectively measuring the quality of documentation can be difficult. To obtain an objective, measurable goal requires carefully observing a user interact with the documentation.

Some of the measurements of documentation could include:

  • the success rate at which the user finds the relevant topic
  • the length of time required for the user to find the relevant topic
  • the average rating given a topic by the users

Another measure could be the number of contacts (phone calls or emails) to technical support. This could be broken down further into:

  • contacts made due to incomplete or inaccurate documentation – for example, a procedure is missing or a field is not explained clearly
  • contacts to report specific documentation problems – this occurs when users give direct feedback on the documentation

After deciding what it is you are going to measure, you can then set a goal based on a specific date or time period, for example:

  • improving the success rate by 15% over the next 3 months
  • reducing the topic search time by 20% over 6 weeks
  • reducing technical support contacts by 10% by August 1

Finally, you need to select an “action item”. That is, what specific action will be taken if the goal is not met?

Ideally, the action would be be implementing a thorough review of the documentation (or portions of it) based on feedback from users or internal staff such as QA, Business Analysts, Product Managers, and so on.  This could include creating a “closed feedback loop” whereby users can directly comment on any topic; the results are then sent to the appropriate writer who will make the necessary changes.

Is this idealistic? Yes. Many technical communicators are already stretched to the limit, so asking them to set aside time to improve their existing documentation is not always realistic. However, for those who are fortunate enough to implement such a failsafe system, the end result is documentation set that actually saves a company money.

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’ in an official document, completing changing its meaning so that federal funding would be denied to an organization. In doing so, and in trying to cover it up later, she signed her political own death warrant.

All information developers need to be mindful of changes. Whether using the track changes feature in Word, or some other system, ideally we should record all the changes made to a document. This is especially true if your documentation is going to be translated.

Tracking changes and using version control also allows you to revert to earlier versions if needed. Too bad Ms. Oda wasn’t using such a system. It might have saved her much grief.

Or NOT.

Meet the new boss, same as the old boss

Mr. Mubarak is updating his resume. After 30 years in power, he was fired after 17 days of massive protests in Egypy. Apparently, his end users weren’t too happy with how he ran the country.

The populace is celebrating the “new Egypt”, but this could very well turn out to be the vapourware of the century. The new boss, Omar Suleiman, worked for the old boss, so it’s difficult to see how things will actually change. This isn’t Egypt 2.0, but more like Egypt 0.0 with some patches.

Moving on to actual software, many technical communicators detest the tools and systems that they work with. It’s tempting to simply revolt and dump the current process, replacing it with anything else.

However, any new tool or system must be viewed with its final result in mind. The two primary questions to ask are:

1. Will it improve the quality and efficiency of the information development process?
2. Will it improve the quality of the documentation itself?

If not, then as poor as the current system is, at least it works.

Whether changing a country or a process, we must remember George Orwell. His classic novel Animal Farm wonderfully documents the failure of the Russian revolution. The men represent the brutal Czarist government; the pigs are the communists. The men are overthrown by the pigs, who turn out to be just as brutal.

The final words of Animal Farm are the most haunting:

“No question, now, what had happened to the faces of the pigs. The creatures outside looked from pig to man, and from man to pig, and from pig to man again; but already it was impossible to say which was which.”

Help! My documents are leaking!

The world has been gripped by one of the sexiest documentation events in history: the release of thousands of sensitive (and very embarrassing) diplomatic cables by WikiLeaks. If there was ever any doubt about the absolute power of information, it can be laid to rest now.

The “documentation manager” of this mess, Julian Assange, is now under arrest, not for leaking classified information, but for sex crimes. This is because sex crimes are sexier than informational crimes.

This event has graphically highlighted the two types of information that we deal with: internal and external. Any information developer who gets these mixed up will run into a world of pain. The problem is that because most information is stored in a “soft” format (on the computer or the web), it is easier than ever for private information to morph into public.

A fool learns from their own mistakes; a wise person learns from the mistakes of others. Let’s learn from this and remember: any private information that you create can easily become public information. Thousands of examples of this happen every day including:

  • damaging emails accidentally sent to the wrong people, or deliberately forwarded to those people, or worst of all, made public (think Climategate)
  • error messages that were not properly reviewed and contain internal comments such as: tell the user not to be so dumb
  • any internal document leaked to the public

Therefore, any information you create or manage should include the following warning:

DANGER!
CONTENTS MAY EXPLODE OR LEAK.
HANDLE WITH EXTREME CAUTION!