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

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

He Said/She Said

Related imageHere’s a word puzzle for you: which pronoun (he or she) would you use to describe a person who has had a sex change? I ask this because I recently read a news article about a female teacher who underwent such an procedure. The teacher now considers himself?/herself? as a man. (Oy – I’m already running into trouble here.) However, the school (a religious one) still views this person as a woman. The author of the article used the title Mr. and the pronoun he when referring to the teacher. Is this correct?

You see the catch-22 here. By using the word he, the writer accepted the position of the teacher, and tacitly recognized the teacher as a man. But if the writer had used the female pronoun, he would have been considered disrespectful toward the teacher. What’s a poor writer to do?

Mutant Hybrid
One solution is to create a new type of hybrid pronoun, something like s/he. Not only is this awkward, it has the side effect of offending both points of view. The solution lies the basic principle of technical communication: Know thy audience.

You see, this entire he/she debacle is not the problem: it’s a symptom of a much larger problem: trying to write the same information for two different audiences, in a vain effort not to offend either. The two audiences are secular and religious.

Secular Vs. Religious
Let’s assume that most people who read non-religious newspapers are secular. So we can safely take the liberal, secular position and assume that whatever someone calls themselves, they are that person. This relates to another aspect of information development.

In documentation, we sometimes have to describe different types of users: basic, intermediate, advanced, and so on. Many software applications will only allow certain functions or screens to be accessed by certain user types. For example, an Administrator will have access to certain modules that a Worker (a regular user) would not.

Who defines these roles? Well, ideally, the person who is working in that role would have to agree, at least on a general level, to that description. Heaven forbid we have a regular user calling themselves an Administrator. That is, the person filling the role helps define the role and needs to agree to the role they are assigned to.

Back to the story – the teacher views himself/herself as a man, and is legally recognized as a man in our secular legal system. So from the secular perspective he is a man. Therefore, the newspaper would be right to use he.

Now, if you are a deeply religious reader, you:
a) don’t read secular newspapers


b) do read secular newspapers, with the understanding that they might “offend” you


c) read only religious newspapers

So if I was writing about this person for a religious magazine, I would use she, because that word reflects the religious viewpoint. Just as secular writers should not be forced into the religious viewpoint, religious writers should not be forced into the secular one.

That is the essence of documentation: writing with your audience in mind.

And you could easily single-source both articles in FrameMaker. God bless Adobe! (Oops…)

The Ten Plagues of Technical Communication

See the source imageThis time of year, my family, along with many others, will gather to celebrate the festival of Passover. This holiday, like all Jewish holidays, can be summed up as: “There was a battle, we won, let’s eat.”

During Passover, we celebrate the liberation of our ancestors from slavery in Egypt. Lest you think slavery is an outdated idea in our so-called modern, free world, simply look at how many people are slaves to their cell phones, Blackberries, to their computers and cars, and to all their other material possessions. The things they own end up owning them. That’s why Passover is one of the most popular and well-celebrated holidays, because the concepts of freedom and slavery are still relevant today.

One of the more colourful segments of the Passover story is the ten plagues brought down upon Egypt. Just as freedom and slavery still exist today, so do plagues. The ones faced by technical communicators are not quite as harsh as blood, pests and wild beasts, but can still cause us great pain.

Here, then, are the modern plagues that technical communicators face today:

1. Difficult reviewers – We’ve all experienced these. Reviewers who don’t return drafts, or return them with such helpful comments as ‘What?’, ‘Needs work’, ‘No!’ or my personal favourite ‘Huh? Reviewers like this need to be placed in front of a firing squad for life.

2. Poor documentation software – Although great improvements have been made over the years, the software for creating documentation is still as not as good as it could be. Microsoft Word is the after-thought of a documentation tool. FrameMaker is quite solid, but still has many annoying quirks. In general, there are few tools, if any, that do everything we want at a reasonable price. We’ve come a long way, baby, but there’s still so much further we could go.

3. Developers – Developers are like dentists – they’re not really appreciated, they cause us great pain, but we need them. They are technically brilliant, somewhat autistic individuals whose greatest strength and weakness is that they focus on the two M‘s: mechanics and minutiae. That’s why developers usually make bad tech writers. If you’ve ever had the misfortune of reading something written by developer, you’ll know what I mean. It can only be described as “mutant documentation.”

The problem is that developers have trouble standing back and seeing the big picture, and that’s where we come in. We sift through the details and extract exactly what the end user really needs to know.

Also, some of the most challenging documentation is that aimed at developers – SDKs, APIs, Technical Guides, Data Dictionaries, and so on. Because it can be very dry and tedious to work on these, the pay is often quite good; you just have to be comfortable writing for Martians.

4. Marketers – The creature who is the polar opposite of the technical writer is not the developer, but the Marketer. Technical writers like to use as few words as possible, and ones that are simple and clear, with no fluff. Marketers, by contrast, like to use many words, often long, unclear, fluffy ones, to overwhelm the reader. Marketers love words and phrases such as: synergize, leverage, empower, paradigm, extreme quality, customer-focused, customer-obsessed, customer-driven, and so on, ad infinitum and ad nauseam.

There is marketing writing, and there is technical writing, and never the ‘twain shall meet.

5. Billboard designers – Although you could lump these specimens with marketers, they are so particularly evil that they must be singled out. Like user guides, billboards are a form of communication designed to quickly impart information. However, many are so poorly designed, I wonder how their designers make a living. The type is far too small or has such poor contrast that it’s almost impossible to read. The sad thing is that companies pay tens of thousands of dollars for this illegible junk.

6. Missing or bad indices – An index is one of the most important elements in any document. Users often turn first to an index to quickly find the information they need, often under stress. A user guide or online help is often only as good as its index. Therefore, good indexing skills are critical. Unfortunately, many writers neglect this important stage. They either fail to include an index, or include a skimpy or confusing one. Put yourself in the reader’s place: wouldn’t you want to be able to quickly find what you’re looking for?

7. Duped docs – Duplicated text is the bane of my existence. I’ve spent more time trying to merge, conditionalize and normalize duplicate copies and versions of text than I care to remember. In one project, I merged twelve Word installation guides into one single-sourced FrameMaker document. It was pure pain, but it sure looks good on a resume.

8. Bad software – A strange and deadly belief has developed that if the software you’re documenting is poorly designed, somehow the documentation will magically fix it. To the deluded who hold this belief, I ask: would you drive a car that had faulty brakes if the user guide warned you they were faulty? Of course not. Still, we don’t want the software to be too easy to use, because then users wouldn’t need any documentation!

9. Outdated documentation – It’s out there, and we’ve all seen it. The docs that haven’t been looked at or reviewed in years, possibly decades. You know it’s a bad sign when you have to travel down into the cold, dark, bowels of your building to try to resuscitate old printouts. Here’s one segment from an old manual I found: “You can send a one-page fax in as little as 27 minutes!”

10. Ignorant Managers – Many managers have no clue about the complexity and challenges that the documentation department faces. The usual response when presented with requests to improve the documentation quality and processes is “Documentation? Hey, I use Word – don’t you guys?” The higher the manager, the greater the ignorance. It’s probably because of the neckties they wear – it cuts off the oxygen to their brain.

Every generation and every profession faces its own plagues, and it’s true that some plagues are “gentler” than others – managers like to call these plagues “challenges.” Challenges are tough but they make us grow. Both Passover and Easter celebrate growth and redemption. Therefore, may we and all our documentation be redeemed this year, and may we all avoid as many of these plagues as possible.

Genesis Redux

Image result for Genesis creationIn the beginning, God created hardware. But the hardware was without form and void. So God said, “Let there be creatures to create the software for the hardware.” And there were software developers. And God saw that they were good.

And God said, “Let there be creatures to test and support the software.” And God created them, and called them “quality assurance engineers” and “technical support analysts”. And the software developers then had the fear of God upon them.
And God said, “Let there be another breed of creatures to sell and manage the software, so that it may reach the far corners of the world.” And God created salespeople, and marketers, and business analysts.

Creepy Creatures
And then God said: “It is not good that all these software creatures should be alone; I will create more creatures to use the software.” And God created a firmament between the software developers and the normal creatures. And God called the developers “geeks”, and the normal creatures, “users”.

And God named the first user, User 1.0, and the second user, User 2.0. And they dwelled in the paradise that God created for them. And the Users delighted in using the software, which was perfect, and without flaws or defect or blemish, and required neither training nor documentation.

The Knowledge Application
And God spoke to the Users, saying “You may use any software you desire, but the Knowledge Application you shall not use. For on the day that you do, you will know pain.”

Now in the paradise that God created, there was the Salesperson, a creature more crafty than any other beast. The Salesperson said to User 2.0, “Did God actually say, ‘Do not run the Knowledge Application?'” And User 2.0 said, “Of all the software we may use, but from the Knowledge Application, God has said, ‘You shall not use, for then you will know pain.'”

And the crafty Salesperson said: “You will not know pain. For God knows that on the day you run the Knowledge Application, your eyes will be opened, and you will be like God, knowing truth and falsehood.”

Original Sin
So User 2.0 and User 1.0 ran the Knowledge Application and saw that it was a delight to the mind, and that it made them wise. And the eyes of both of them were opened. And they saw that their software had a defect, so they called tech support.

And God saw that the Users had called tech support and called out, angrily, “Who told you that the software had a defect? Have you used the Knowledge Application which I commanded you not to use?” And User 1.0 said, “The User 2.0 you created gave me the Knowledge Application, and I ran it.”

Then the God said to User 2.0, “What is this you have done?” And User 2.0 said, “The Salesperson deceived me, and I ran the Knowledge Application.”

Vengeance is Mine

And God said to the Users: “Because you have partaken of the Knowledge Application, you will know pain. You shall be confounded by software and hardware, and you will know of endless bugs, and system crashes, and application instability that will drive you to madness. And you will require extensive training, support, maintenance, upgrades, and documentation so that you will be able to use the software.”

God’s Finest Creature
And God said, “Let us make one final creature, in our image.” And he created the Technical Writer and blasted the knowledge of the software into it.

And God said to the Technical Writer: “Behold, the world will come to know you as the creator and keeper of all practical knowledge. And this is a heavy burden, for you must keep the following commandments:

  1. You shall make the meaningless meaningful and the incomprehensible comprehensible.
  2. You shall provide truthful and accurate communication to all Users.
  3. You shall dedicate yourselves to conciseness, clarity, coherence, completeness, striving to address the needs of those whose products you document.
  4. You shall serve the business interests of clients and employers, as long as such loyalty does not violate the public good.
  5. You shall contact your clients and employers when you believe material is ambiguous.
  6. You shall negotiate realistic, candid agreements on schedules, budgets, and deliverables with clients and employers in the planning stage.
  7. You shall seek to promote the public good in your activities.
  8. You shall avoid conflicts of interest in the fulfillment of your professional responsibilities and activities.
  9. You shall seek candid evaluations of your professional performance from clients and employers, and shall provide candid evaluations of communication products and services.
  10. You shall advance the technical communication profession through integrity, high standards, and performance.

A Powerful Promise
And God said: “If you follow these commandments that I have given you, you shall be respected, and prosper, and be as numerous as the stars. But if you stray from these commandments, then you will know my wrath, and the world will despise you and curse you and the user manuals you create, and will never read them.

“So know this – today I set before you a choice between good and evil, between knowledge and ignorance. Choose knowledge, so that you may become wise. And if you do, it shall come to pass that the world will be in awe of you and will seek your wisdom and counsel. And clear and concise information will fill the world as the oceans and the sky. And you will be blessed and called ‘a people of the book’. And ignorance and poor documentation will cease to be…”