Single-Sourcing My Life

Image result for mail overloadI was determined to avoid email bankruptcy, the fate of Internet commentator and legal expert Lawrence Lessing. Lesson was so overwhelmed with the volume of emails he received that he sent a mass email back saying he’d probably be unable to respond.

My problem was not the volume of email, but the fact my contact information was spread out over many different files, and over several different computers. I use up to four different computers a week, so I knew I had to get my email on the Net. After much informational detective work, I consolidated all my contacts’ email addresses, phone numbers and other data into a single online location. It’s a beautiful thing.

You’ve Got Mail (And A Bunch of Other Stuff Too)

Of course, being an “info junkie”, I couldn’t stop at email. I also moved my web favorites online, as well as certain documents that I wanted to view and edit anywhere, just like this Blog. (This comes in handy when your teen-aged daughter kicks you off the computer.)

The Battle for Storage: Please Take It Offline

Clearly, online storage has its advantages. However, so does storing files locally, as the following list indicates:

Access to Files:
* Local Files: Limited to specific computer only
* Online Files: Any computer with Internet access

Application Features:
* Local Files: Many
* Online Files: Fewer, but growing

Application Updates:
* Local Files: Less frequent
* Online Files: More frequent, and often free!
Ability for others to comment and add metadata:
* Local Files: Limited
* Online Files: Widespread

Speed:
* Local Files: Fast
* Online Files: Slower, but getting faster

Security/Privacy:
* Local Files: Better
* Online Files: Potential risk

Backing up:
* Local Files: Must do
* Online Files: Somewhat optional; data is stored “off-site”

Potential for duplicate data:
* Local Files: High
* Online Files: None

If Internet connection is down:
* Local Files: Can still access files
* Online Files: The horror, the horror

As Internet speed, technology, features and security improve, more people will shift their information away from a specific machine and onto the Web. In fact, in the not too distant future, we’ll just log on to any machine anywhere, and have immediate access not only to all our files, but our entire desktop and all our custom settings and applications. The customizable websites of today (such as iGoogle, Yahoo and Facebook) are but a taste of tomorrow.

Lining Up Online and Offline

The amount of information we already access online is extraordinary. Banking sites, social and professional networking sites, and blogs are all accessible anywhere. Yet there is still much data trapped within our specific machines.

For example, I haven’t really single-sourced all my contact information. It’s still duplicated in Microsoft Works where I can create custom lists and reports, and again in the speed-dial information on my various phones. True single-sourcing would allow us to enter the information once and use it on any device, reformatting as necessary.
Feed Me

An excellent example of this type of content reuse is found in the wide variety of RSS readers. (This blog automatically creates an RSS feed.) All RSS feeds are in a standard XML format, allowing you to follow them using the readers (or browser) of your choice. Most importantly, you can change the appearance of the information, sort it and categorize it.

The Para-Docs

Now, technical communicators, being the “techie” types we are, are heavy creators and users of customized Internet data. This leads to a rather odd paradox.

During our personal time, we create and store data on the Internet, with all its inherent advantages. Then, during our working time, we manage documents that we can edit only on one computer – our company desktop or laptop. Even those of use who are lucky enough to work at home occasionally still have to schlep our laptop back and forth to work. Finally, the documents we work on are printed or packaged with the software. The layout and formatting are fixed and the content is frozen.

They say that a picture is worth a thousand words – what’s wrong with words in this picture?

Some companies are beginning to realize the absurdity of creating documents that can become outdated moments after they are produced. As a result, these businesses are providing more of their content within secure online locations. PDFs and Word files may be quick and easy to produce, but they represent an antiquated model of communication.

Don’t Bury Me – I’m Not Dead Yet!

Of course, traditional documentation won’t completely die. They’ll always be a need for hard copies, especially for hardware and other equipment, where printed quick start and setup guides are essential. However, we will see more content shifting online, as companies strive to cut costs and stay current.

Don’t WORA, Be Happy!

Java developers say: write once, run anywhere (WORA) to indicate that they only have to write a program once and it will run correctly, regardless of the platform.

Information developers need to say: write once, access anywhere. Create, edit and read what you want, where you want, when you want and how you want. Otherwise, we’ll all be declaring documentation bankruptcy.

The Green Machine

Image result for green partyElizabeth May, leader of the Green Party, appeared to have won a major victory by being allowed to participate in the debates for the 2008 federal election. Technical writers are, above all else, a practical tribe, so let’s analyze this from a practical perspective, shall we?

Ms. May was allowed into the debates. Did everyone actually watch the debates? No.

But let’s say everyone did watch the debates. Would this have necessarily influenced their vote? No.

But let’s say it did influence a few votes. With our first-past-the-post voting system, even a major increase in the number votes would not necessarily lead to more seats.

But let’s say it did actually lead to more seats. Would it necessarily mean many more seats, to the point where they would actually wield any power? Probably not.

But let’s say it did lead to enough seats to actually influence the government. Is there any reason to believe that changes enacted would have a real, practical effect on our daily lives? Again, probably not. In fact, how you manage your career has far greater impact on your wealth and happiness than the act of inscribing an ‘X’ on a small piece of paper and inserting this into a cardboard box.

Now let’s go back to the original issue: whether May should have been allowed in the debates. We’re talking about something that probably had no effect on something that will probably have no effect on something that will probably have no effect on something will probably have no effect. In other words, this is an issue where people reacted disproportionately to the importance of the issue.

You may kill yourself trying to write a description of a field in a dialog box, a dialog box that is rarely used, in an application that no longer sells, for a user guide that no one may be reading. Ask yourself – is it worth the effort? Perhaps you should be focusing on improving the documents that people are actually using.

Labels and other dogs

Related imageHere I am, in my basement, surrounded by mountains of dog food I’m desperately trying to organize. We own one dog, an odd-looking labradoodle named Jessie, however, my brother-in-law’s dog Gracie often visits. Both dogs need feeding, therefore I own two large plastic containers filled with food for each dog, and both dog food types look almost identical. I wonder: What is the best way to label each container?

The obvious labels would be Jessie and Gracie, however I often get the dogs’ names mixed up even when I’m around them; Jessie and Gracie simply sound too similar, and the dogs themselves do not carry signs that clearly identify them. I decide on the labels Our dog and David’s dog, eliminating all confusion.

Labels are everywhere in documentation, specifically in:

  • the name of a document: User Guide, Admin Guide, Install Guide, and so on
  • chapter names
  • heading titles

These are all critical identifiers, and just like the dog food box labels, they need to be clear, descriptive, as short as possible, and leave no room for confusion.

As an example, our company used to create Installation Guides, but this was not descriptive enough because it did not distinguish between guides for users who were installing our software for the first time, and guides for users who were upgrading an existing version. We therefore changed the document titles to:

  • Guide for New Installations
  • Upgrade Guide

Chapter titles and headings also need to be clear and unambiguous. Documents is vague, Creating Documents is better, and Creating Documents on a Database may be better still, especially if you need to distinguish between this topic and creating documents in another location.

Labels are also in software in the form of fields, menus and title bars. Experienced technical communicators provide valuable feedback and insight for the naming of these items. As with documentation labels, software labels need to be clear, consistent and leave no room for confusion.

I’ll share an interesting example.

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 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!”

More exotic things I have be asked to label include database tables, attributes and elements. It can be very challenging, and very rewarding to give these things the right name, one that nearly sums up the essence of what the thing is. So choose your labels carefully – they can turn good documentation into great.

Now excuse me while I go feed the dogs…

The Time-Traveling Tax Man

See the source imageI’m one of those incredibly annoying people who file their tax returns early, in order to get my refund early. I file electronically using a service called Netfile. You can check the status of your return online using the CRA’s “My Account” service. Eventually, you’ll see a message like this:

Your 2007 return was assessed and a refund of $500 was deposited directly into your bank account on May 3, 2008.

The problem is that this message appears long before the actual deposit date, because there’s a delay in the processing of your refund and when you actually receive your refund. Therefore, it’s wrong to say “was deposited” when it hasn’t even been deposited yet.

Imagine you are the technical writer and have been assigned the task of fixing the wording so that it is logically correct. What are the options?

One solution is to do nothing and justify the error by saying that the wording will only be wrong for a few days or weeks, and then it will be correct. It’s a bit like saying that a stopped clock is correct twice a day. In otherwords, it’s a cop out.

Another solution would be to say “a refund of $500 was/will be deposited” but this is even more confusing than the original wording.

One more solution would be to implement a script that would automatically change the wording from “will be deposited” to “was deposited” on the magic day. The problem is that this would be complex and costly to implement, and like all programs, would be subject to error.

The cause of this problem is the verb was, in the phrase “was deposited”. We need to get rid of this, but how?

Here is what I would suggest:

Your 2007 return was assessed:
Refund amount: $500
Deposit date: May 3, 2008.

Refunds are deposited directly into your bank account.
That’s it! Proof that fewer words are often better, and that the simplest solutions are often the best. Now go file your taxes already!

Six Things That Should Be Single Sourced

Image result for single sourceSingle-sourcing, as we all know, is the art and science of using a single repository of information to produce multiple outputs. Typical examples include creating a PDF and online Help project from one source, or creating different versions of the same manual for different user types. It is one of the most valuable weapons in the battle to tame the information monster.

Of course, single-sourcing has been used for many years in other industries, particularly in programming. Developers use object-oriented programming to create re-usable modules (or “classes’) of code. These modules are stored and maintained in one location, and used as necessary. Object-oriented programming is called “OOPs” for short. “OOPs” is also something programmers like to say when they realize an entire module is missing from an application that has just been released.

A Single-Sourced World

Single-sourcing has even been applied to industries outside of software. Car makers, for example, design their cars so that a spark plug for one engine will fit in other engines. This process of standardization is a form of single-sourcing that reduces maintenance and assembly costs, although probably won’t be enough to save General Motors – more on this later.

Single-sourcing is such a powerful idea that I see no reason why it can’t be applied to other areas:

 

  1. Light bulbs – Have you been to a hardware store recently? There’s about 200 different kinds of light bulbs to choose from. Halogen, fluorescent, incandescent… Remember the good old days when there was just one shape of light bulb, and the only variance was the wattage? Have you ever tried to change a halogen bulb? It’s easier to put braces on a mosquito. I say single source it – one light fixture for all.
  2. Screws – Continuing on the subject of hardware, can someone explain why there are so many different types of screws? There’s the screw head drive patterns: slotted, Philips, raised, torx, hex, Robertson, tri-wing, torq-set, spanner, and my personal favourite, pozidriv. Additionally, there are different head shapes: pan head, button or dome head, round head, truss head, flat head, oval or raised head, bugle head, cheese head (I’m not making this up), fillister head, socket head (what we call an uncooperative reviewer) and headless (like the horseman). To further complicate things, there’s metric and non-metric sizes. To paraphrase Murphy’s law: the odds of having the correct screw at the correct size and shape and the correct tool for it are inversely proportional to the importance of what you are trying to attach. Surely some of these shapes, patterns and sizes could be amalgamated. Otherwise, we’re screwed.
  3. Cars – As indicated earlier, the Big Three automakers don’t seem that big anymore, with Ford and GM posting record losses, and Chrysler probably not far behind. Eventually, these three companies may have to merge – single-sourcing at its finest. But why stop there? Why not just have one car company throughout the world? Yes – it would be a monopoly, but think all of the money that would be saved in research, marketing, advertising and so on. Far fewer parts would have to be manufactured and maintained. Mechanics would just have to know how to work on a few different cars instead of hundreds. Buying a car would be easier and faster because there would be fewer choices. We could give this new car company a catchy name, like “Toyota” or “Honda”.
  4. Language – What’s with all these people that don’t speak English? Everybody knows it’s the official language of the universe. Want proof? Watch any Star Trek episode – no matter what planet is visited, its inhabitants speak English. Do you know how much money is wasted translating information into various languages? The time and effort to learn other languages is staggering. We desperately need to single-source language – everyone speaks English from now on. And if you don’t like it, well, hasta la vista, baby.
  5. Political parties – It’s going to cost $270 million dollars to have an election. Didn’t we just have one? What a waste. Let’s avoid this nonsense now and forever and just have one party. Think of all the money and time we’d save! No more election campaigns. No money wasted on the “official” opposition. Everyone would do their own thing and we’d leave the government to do theirs, without having to be bothered every few years putting a silly little ‘X’ on a piece of paper.
  6. Countries – And since we’re on the subject of politics, why do we need so many countries? Couldn’t some or all of them be merged? Instead of having to pay for hundreds of governments and leaders, we could just have one. Everything would be consistent and standard from country to country. Travel would be easier because you’d no longer need a passport and everyone would speak the same language.

I Have A Dream, and it is Single Sourcing…
This is the vision. This is the dream. Soon, we will be able to celebrate the glorious anniversary of these single source directives. We will create, for the first time in all history, a garden of pure ideology. Where each worker may bloom secure from the pests of contradictory and confusing truths. Our unification of thoughts is more powerful a weapon than any fleet or army on earth. We are one people, with one will, one resolve, one cause. Our enemies shall talk themselves to death and we will bury them with their own confusion. We shall prevail!