The Doc Particle

Never has something so small attracted so much attention. In July of this year, scientists at the Large Hadron Collider, the world’s largest particle accelerator, claimed to have discovered the oddly named Higgs-boson particle. (And it only cost them $10 billion to find it.)

 

This tiny particle is also known as the God Particle because it could explain why things exist.  Discovery of the Higgs-boson particle helps prove the existence of something even more bizarre: the Higgs field. This is an invisible force field which covers the entire universe, allowing subatomic particles to have mass. Without mass, electrons, protons and neutrons wouldn’t be able to form atoms, and therefore nothing would exist.

This discovery could lead to some amazing things. If scientists could actually control the Higgs-boson particle, we could travel at the speed of light and change matter. Science fiction would become science fact.

The idea that there’s a force holding everything together is fascinating. We think that things just are - that they exist in a simple, natural state. The fact that things may not be so simple, that it actually requires a force to hold everything together and give a structure to all matter, is mind-blowing.

But the question for technical communicators is this: what is the force that holds all content together? By content, I mean any organized collection of information that forms a document, help system, website,  or any other form of visual communication.

Whatever this force is, it must be as powerful as the Higgs field, for without this force, content would descend into a universe of chaos, with thousands, if not millions, of elemental pieces of information flying off in every direction.

Specifically:

• Topics would have no context or structure.
• Concepts would have no meaning.
• Indices would include non-existent entries.
• Tables of content would cease to exist.
• Tasks, the backbone of many user guides, would describe inaccurate or irrelevant steps, and would omit key steps.

One shudders to think how it would all look, but having an engineer write a user guide gives a fair approximation.

So just what is the force that holds all this content altogether? The answer is so obvious that you would not even suspect it – it is technical communicators. We are the force that holds content together. We create it, shape it, fine-tune it, and then re-shape it again until it forms a living system of information that is practical and meaningful to the end user.

We have seen the God Particle of content, and it is us.

Read More

Brand me a surrogate

Surrogate advertising is a fascinating form of marketing. It conveys a specific brand or product but appears to be for an entirely different brand or product. In other words, it's a form of "guerrilla" or "Trojan horse" communication, because it very carefully hides the intended message within a larger message designed to distract the viewer.

Corporations often engage in surrogate advertising because it's illegal for them to advertise their product directly.

One example of surrogate advertising is Russian Standard, makers of a popular vodka in that country. They branched out into a completely different industry, banking, to form Russian Standard Bank. The bank was a success because the brand was so well-liked. When they advertise their bank, they're really advertising their drink.

Here in Canada, President's Choice supermarkets have branched out into banking, credit cards, cell-phones and even pet insurance. If people like the brand, they will consume it in all its forms.

Technical Writers, The Brand
Here is the perceived "brand" most people have of technical writers:

Technical writers are highly technical, social awkward, introverted, geeky bookworms who write documents all day long.

We must use the principles of surrogate advertising to completely redefine and expand our brand to include everything that we do for our clients. This is especially true if we are contract workers, who are expected to be complete business communication service bureaus.

What's in a name?
The first challenge is with the name we give ourselves. Most people are familiar with the term technical writer. We must educate people on the more expansive and inclusive term: technical communicator.

After changing our name, we can then completely rebrand it:

Technical communicators are highly observant, objective, practical, and dynamic professionals who create, manage, and enhance all forms of visible communication, both internal and external, including information, documents, and the products themselves.

The bottom line
Although we do not sell products, we increase profits by helping people understand how to use a product or service, thereby lowering calls to technical support.

We also boost profits by giving clear, practical, and objective advice on the design and usability of a product. This not only lowers support costs, but can increase sales by instilling goodwill in customers, and increasing the chances they'll recommend a product or service to others.

In other words, technical communicators help companies make money.

Our products and services
The types of communication we work with include:

• any type of guide or document: user guides, installation guides, technical guides, online help, tutorials, training guides, policies and procedures, functional specifications, technical references, legal and medical documents, and so on
• marketing communications, including Release Notes and press releases
• websites, wikis, intranets, blogs or any other online document

We also offer the following value-added services for businesses:

• simplifying and clarifying complex documentation
• reviewing software, websites, and documents from a usability perspective
• analyzing a company's current documentation processes
• developing corporate style guides
• content strategy and planning for various media including print, online, and mobile
• single-sourcing: merging duplicate content into one source
• rewriting error messages
• writing practical on-screen instructions
• creating effective online surveys
• developing clear names for programming objects, classes, rules, fields, and so on 
• managing a company's online social media presence

We may also offer the following services for individuals:

• creating and editing résumés and cover letters that will ensure you get an interview
• completely reviewing your online profile, including LinkedIn, Facebook and Twitter, to ensure your image is professional and consistent
• helping you develop an effective blog or personal website

From brand to surrogate brands
Therefore, while our main product brand names might be one of:

• technical writer
• technical communicator
• information developer

 our surrogate brand names include:

• training developer
• product evaluator
• usability expert
• software tester
• policies and procedures writer
• content developer or manager
• marketing communicator
• content strategist
• survey developer
• information simplifier
• style guide developer
• UI and error message text developer
• programming elements 'namer'
• documentation project manager
• website enhancer
• career documentation specialist
• social media manager

As with any good brand, we need an effective tagline or slogan.

I suggest:

Technical Communicators: We make things clear, concise, and complete.

Read More

Trinity, One Two Three

People are innately drawn to things in threes; to objects in triplicate. There's the classic Christian trinity, where God is divided up neatly into three parts: the father, the son, and the holy spirit. But there are many other trinities:

• mind, body and soul
• thinking, feeling and acting
• work/life/play balance
• the division of pregnancy into three trimesters
• animal, vegetable and mineral
• Christians, Muslims and Jews
• protons, neutrons and electrons
• the First, Second and Third Worlds
• sex, politics and religion
• family, friends and co-workers

In addition, Starbucks Coffee developed the idea of "the third place" outside of home and work, where one could simply relax while drinking $6 lattes. Clearly, people are attracted to threesomes, but why?

It could be that three represents a careful, comforting and symbiotic balance. While it's true that just two things can "balance" each other (picture two equal riders on a see-saw), extending the number to three seems to add that extra element of desired symmetry. Each of three balances out each other in a psychologically pleasing way.

DITA, an XML markup language that is revolutionizing how content is stored, created and managed, also uses a trinity. In DITA, all content is stored as individual, modular topics. There are three basic DITA topic types in which all content can be classified: concepts, tasks, and references.

1. A concept topic describes what something is or why you would perform a task. It gives the idea behind something; the background information that the reader needs to know.
2. A task topic gives detailed, step-by-step procedures for a specific action. It can include pre-requisites and expected results. It is one of the most common topic types.
3. A reference topic contains technical material, specifications, lookups and other detailed information, often in a table form. Examples include command references, allowed values, lists and catalogues.

Now, what's very important to remember is that you should never mix the content of each of the parts in this holy trinity together, for you will surely burn in content management hell.

For example:

1. In a task, do not include a detailed explanation of why you would perform this task. Maintain this background information in a concept, then, if necessary, link it to the task topic.
2. In a concept, do not include procedural steps. Keep these steps in a task topic.
3. If there are many possible values to choose from in a task, do not include them in the task, but in a reference topic instead.

You can see, therefore, that this trinity of topic types covers all your information needs.

And it's as easy as 1-2-3....

Read More

Tech Writer Confidential

What do a doctor, lawyer, and priest have in common? A very special arrangement with their users which ensures total confidentially. It goes by different names, depending on the profession.

For doctors, it's doctor-patient confidentiality; for lawyers, attorney-client privilege; for priests, priest-penitent privilege or clergy privilege.

Whatever its name, the principle is the same: that all communication between the professional and the client is strictly confidential. It's an important principle because it helps ensure full, open, and honest communication.

A similar principle applies to our profession: communicator-reviewer privilege. When we review a document with someone, there's an implicit understanding that everything the reviewer says is private. However, we also need to make reviewers aware that if they make a comment on a draft, it could be shared with others. Also, if they raise issues that require us to do further research with others, we need to make the reviewer aware of this.

If reviewers can't trust that what we discuss with them will remain private, they won't make very good reviewers. An informational wall will be built up, and it's a very hard wall to tear down.

An even more important principle of confidentially we follow is communicator-client privilege, where the client is the customer or company you work for. It's an important and legally-binding rule that we don't divulge inside information to public end users. Clients must know and trust that we will keep internal information private, otherwise they won't us with their documentation.

Now, this can lead to awkward situations and moral dilemmas. What if you discover that one of the features you're documenting does not function as it described? It would not be advisable to start tweeting this fact or posting the problem on Facebook. Your obligation is make the owners of the product (the product manager, the development manager, or both) aware of the problem in writing, via email. If a higher-level manager ever inquires about it, you can show them the email you sent. Now it is no longer your problem - it is their problem.

Confidentiality, therefore, is one of the cornerstones of our profession (along with other c-words such as clarity and conciseness.) Without it, the technical communication process simply won't work. Confidentiality can only occur if there is trust from the person or entity giving the information to the one receiving it. The person giving us this information is "lending" it to us, with the understanding that we won't share it unless given permission to. The information lender must be confident that we will keep what they say private.

And that is why the first word in confidentiality is confident.

Read More

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?

Read More

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.

Read More

iHate unclear product names

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

Read More