Technical Writing Knowledge Papers

The “Hidden Costs” of Gettin’ It Wrong

©2016 Mark Henderson

I had a recent meeting with a potential client, and one of the topics we discussed was the oftentimes grossly underestimated—or even completely UN-estimated—costs of equipment and machines “going down”. While the subject wasn’t integral to our decision to collaborate on his project, what struck me was the fact the he got it. He understood the unknown or hidden costs of unplanned outages of productivity-critical equipment and machines.

On the flip side, I can’t tell you how many people I encounter in my “professional nomad” career, zig-zagging across various industry sectors, who just don’t appreciate the true costs of stuff failing to do what they need done to make a buck.

As an example, let me cite one I read about some time back:  There was a company that made something we’ll cliché-call “widgets”. Now, their widgets came in differing configurations (e.g. size, color, strength), but all were prepped for and shipped from a single point in the plant. The reason for this was that the machine they used to mark, crate, and ship each order of various widgets was a very expensive machine at the very end of the production lines and bins conveniently located for easy loading. Like any other machine on this planet, their machine experience downtime—planned (i.e. periodic maintenance) and unplanned (i.e. repairs). What was interesting was that their cost-per-minute for downtime was based on some simplistic formula like gross daily sales ÷ 24 hrs. ÷ 60 min. or something similar. The problem was (and pay attention, because herein lies the heart of this issue), this simplistic formula failed to account for the sea of people who were costing salary (not to mention all the other costs to keep the lights on) during a periods of time when zero revenue was being generated! When their choke-point machine was down, no product was being shipped, no sales orders were being filled, and no invoices were being sent. In other words—to paraphrase an old saying, “The lights were on, but no-money’s home”.

When the previously hidden costs became known, and a more realistic and accurate (a.k.a. real) downtime cost-per-minute value was determined, it became a corporate “state of emergency” and this company invested heavily to procure a second machine and build all the supporting infrastructure required to have a complete parallel load-ship system so that at least one line was up and shipping at all times. And this was no cheap or easy fix, but I understood that the company calculated a positive ROI within the first six months!

Certainly not all hidden costs of getting it wrong are this lopsided (my own euphemism for ridiculously costly). However, back to my original observation:  Few professionals take the time to truly identify, understand, and calculate the real costs of downtime or error. If they did, I am certain more decision-makers would place a much higher value—dare I say “corporate state of emergency” value?—on developing and maintaining clearer documents, records, and data to try to make sure that everyone responsible for producing or doing whatever it is they produce or do for revenue is done productively and done right. It’s those hidden costs of getting’ it wrong that need to be fleshed out in order for a business to make sound business decisions whether to invest in the documentation to make sure that everyone gets it right.


Why Dangle Me Participle and Shiver Me Timbers:

He’s Struck a Pernicious Nuance!

©2016 Mark K. Henderson

Technical editors fear nuances. They’re akin to land mines when your job is to make a safe, straight, sensible path for others. Technical editors’ fear & loathing of sneaky nuances is only matched by the fear & loathing of a computer science engineer being tasked with writing an expository paper on Keats…for presentation to the class.

pirateWhile I dare say that most readers will have a pretty good grip on the CS engineer’s dread of presenting a dissertation on Keats, some might not catch the big deal about every technical editor’s nightmare—the pernicious nuance. The source of the angst lies in the nuance. (If you didn’t get that, hold the thought and come back to it when you finish reading.)

Nuance phobia does not affect an editor performing what’s commonly called a line edit. An editor performing a line edit scrubs for defects such as typos, misspellings, maybe a misused word, and the like. The line editor is bullet-proof when glossing over nuances.

However, for the technical editor performing a thorough “conceptual edit”, the challenges are more in-depth:  Does each word-choice and phrase make sense? Is the information logically presented and organized to convey the idea(s) the author intended for the target audience? Are new concepts, ideas, and terms sufficiently explained? And the list goes on…The editor’s challenge, then, is to do whatever it takes to get the document right (a.k.a clear and concise), but without changing the technical meaning of a document (i.e. rendering it invalid).

Enter in nuance:  The nuance lies in ambush inside these documents, because the nuance lies on the fine line between greatly improving a document or erroneously changing its technical meaning. It’s the nuance of meaning in the author’s words and what he or she intended.

Perhaps an example would be helpful. A while back, I was tasked with performing a thorough conceptual edit to a plan for maintaining electrical components in and around detonable atmospheres and other hazardous environments. I was given wide leeway to “make it right”.

Unfortunately, I didn’t even get past the overview before I hit a what I suspected to be a live nuance. Specifically, the nuance was the way author used the phrase “levels of containment”. While some of the other thoughts and phraseology needed work, I could tell contextually his usage of that phase was intentional, and I suspected that there was a nuance to the meaning that I did not understand.

Even though I called him right away, since he wasn’t immediately available and I was on an aggressive schedule with his document, I took a shot at revising the overview section based on my experience and my understanding of what is typically meant by “levels of containment”.

As soon as he got my message, he came down to my desk and spent about 20 minutes on a dry-board literally illustrating the traditional approach versus the contemporary philosophy for managing devices in these high-hazard environments. During this excellent tutorial, I realized immediately that—as comedian, Ron White is wont to say—“I was wrong.”

So I completely scrapped my first revision of this plan overview and was able to make the necessary revisions to get the document right. When we were finished, my subject matter expert (SME) was, in the words of the late Sen. Hubert Humphrey, “tickled pink” with the product. But, it took truly learning and understanding the nuance meanings of his phrase before I could successfully get the document right and not change the technical meaning of what the author intended.

So, for those of us charged with editing documents to get them right, don’t fear the pernicious nuances of what a SME might provide; rather, read what the author developed, and then try contextually to determine the intended meaning and whether some phrase or word choice was intentional.

Of course, when a technical editor suspects the presence of nuance, it’s best to immediately tag up with the author/SME so he or she can explain the meaning and their intent.

And for you readers charged with authoring documents for your technical editor to do their conceptual edit, take a page out of my SME’s playbook and take the time to explain the intended meaning, or nuance, of what you wrote. It will help your technical editor make your document clear, concise and valid before he or she inadvertently changes it technically while trying to make it right.


The Techno-Creative Conundrum

©July 6, 2015 Mark Henderson

One of the things I’ve observed in dealing with business people and individuals considering their options for developing their book is that most of these people seem to have pre-formed distinctions between technical or business and creative writing. And, while these types of writing are written for very different purposes, for very different audiences, and are therefore, by necessity, quite different in style, they are still writing—written communications intended to convey information from author to reader.

As professional writers and editors, we are called on to write for all types of audiences over all types of media in all manner of styles. But, what we find is that most folks share some sort of secret belief system that the writer who produces technical writing cannot author powerful prose, or the writer who develops transactional business rules and processes cannot produce compelling copywriting, or poetry, or memoirs. It is, what we call, “The Techno-Creative Conundrum.”

But to us, there is no conundrum—other than having to convince others—between technical, business, and creative writing and editing. This is partly based on our work for a vast array of clients and a vast array or documents finding their intended marks across a wide spectrum of audiences. But, it is also based on a fundamental belief, or recognition rather, that all writing is both technical (i.e. structured) and creative.

“Say what?” you ask.

Yup. All writing is both technical and creative.

Let’s look at the creative side first. Let’s say, for just a brief example, Julie wants to write a story about how she became a CEO of a large company starting out as a sharecropper’s daughter. The story is there—she lived it and knows the facts. It’s up to somebody to write it and to write in a compelling way that reaches her target audience and not only communicates her story as a matter of facts; but rather, compels her readers to identify with her, to feel what she felt or feels, and in essence, to think along with her. It’s definitely going to take some creativity to do that. But without some technical discipline, without some structure, it’s going to wind up as some sort of “stream-of-consciousness” drivel that nobody with get. This story will require “structure”—technical discipline, if you will.

Starting with the most basic elements of written communications—sentence structures or compositions—moving to conceptual conventions such as when in the story to relay certain informational elements and how best to create and resolve conflicts, etcetera. And need we add agreed-to conventions of style, punctuation, grammar, and more, all of which are rules or disciplines of writing that provide structure to any good story.

But what about the technical writing side of the conundrum, you might ask? Where is creativity required in such writing?

Here’s a quick example. Let’s say the business needs to develop a form and a procedure for starting up huge uninterruptible power supplies (UPSs). Furthermore, it’s important to the business to gather data on the form, and to be able to find key elements of information at any point in the future.

The “strictly technical” side may elect to create a form for technicians to fill in blanks, develop a start-up procedure for each model of UPS that refers to the form, and then archive the forms. However, with a little creativity, the technical writer can create the procedure and the form in the same document. With some collaborative creativity, the writer may coordinate with the IT folks to create this instruction/form with the key fields placed so that the critical information from every UPS start-up can be archived electronically and searched on parameters important to the business.

Hopefully, without citing a nauseating series of examples for both creative being technical and technical being creative, we’ve made some headway into solving the “Techno-Creative Conundrum”.

I love what I overheard an anonymous senior runner at the Little Rock Marathon:  It’s all about the people, baby! It’s all about the people. In the case of technical versus creative writing, in a nutshell, it’s all about the people. Great technical and business writers and editors utilize tremendous creativity in producing documents that hit the mark; great creative writers use tremendous technical discipline and structure—even technical descriptions—in creating compelling creative writing that communicates the author’s message in a way that makes the reader go, “Wow! That was good.”


Setting the Table for Success:

Forming Winning SME-Writer Teams

Part I

©2015 Mark Henderson

In my profession as a consulting technical writer, I have a critical dependency on the subject matter experts, or SMEs, to create technically valid deliverables on a schedule. Nobody knows the guts of the matter better than the SME. Even if I bring some previous experience with and knowledge about whatever subject I am starting, I like to paraphrase one of Liza’s best lines from the film, Gone With the Wind:  “I don’t know nuttin’ about…no [fill in the blank]!” I look to the SME—first, to help me understand whatever it is they know or do in the context of my mission (such as a procedure, or a plan, or user’s guide). Next, after I develop my first cut, I need the SME to validate the product. That is why this relationship is critical, not just for me, but for the quality and schedule of the product.

An interdependent relationship between the SME and technical writer is critical to the quality and schedule of the product.

Over the years, I’ve teamed up with numerous SMEs to produce a myriad of documents. And for the most part, I’ve been blessed with great SMEs—highly competent and sharing the same priorities. However, some of these successful relationships didn’t always start out like Cinderella and the handsome Prince; rather some started out like Cinderella and the step-sisters, and it was ugly. Personalities aside, most, if not all, of these latter relationships could have been improved had someone taken the time to set the table for success. Let me explain.

Most of these “slow starts” initially shared a general common initial roadblock:  That is, they weren’t set from the beginning to succeed. They weren’t initially created to be interdependent relationships. I’ve even showed up to visit SMEs who were totally surprised at my appearance and why I was there! From my knothole, that is never a good way to start.

Many “slow starts” happen because they weren’t set from the beginning to succeed.

I’ve also had SMEs who were wary of me, but more so, of what I was tasked with producing, suspecting that whatever I produced was going to negatively impact their livelihood, or at least the way they did what they did day-in and day-out.

So, how do we, as a client–consultant team, set the table for success? The answer that I’ve heard promulgated from professionals of “my feather” (i.e. other technical communicators) is the project kick-off meeting. I respectfully disagree; I think the project kick-off meeting is too late. I believe that SME discussion needs to be a client in-house meeting:  Why the business needs to expend the resources to do this—what are the business reasons; why the SME was selected; what does the SME need (extra resources, schedule realignments, etc.) from the organization to be successful. Whatever needs to be communicated to get SME buy-in and to make him or her not only available for, but committed to the project and “resourced” for project success.

The SME discussion needs to be a client in-house meeting, before the project kick-off meeting.

After y’all talk amongst yourselves, of course, I love seeing my SME(s) at the project kick-off, at least when practical and that formal meeting doesn’t terribly jack with their day right out of the bag. But, I observe during project kick-off meetings whether my SMEs are on-board “GO-TEAM-GO!” guys, or whether they feel like someone just dropped another task on their already over-subscribed task plate. Regardless, I am going to strive to create the interdependent relationship that we all need to be efficiently successful because I really like happy endings!

So, let me end this thought paper on a happy note:  We had a project kick-off at a client’s site, my project SME walked into the room at exactly meeting start-time, the meeting was over in 15 minutes, and ‘Joe SME’ escorted me out onto the floor. He says, “Thank God you’re here! If they didn’t bring you on, they were going to try to make me write these…!” That, friends, is interdependent relationship Bonus-land! And yes, it created a very happy ending:  Together, Joe and I created the full scope of clear, concise, & valid task procedures ahead of schedule. And to my knowledge, they’re still in use today.

Joe SME escorted me out onto the floor and said, “Thank God you’re here! If they didn’t bring you on, they were going to make me write these…”

[In the second installment of this thought paper, I’ll discuss in greater depth some specific methods for setting the table for success to create effective and efficient SME-writer teams.]


Setting the Table for Success:

Forming Winning SME-Writer Teams

Part II

©2015 Mark Henderson

As we discussed in the first installment, there are some things we can do to “set the table for the success” for your subject matter expert (SME)-technical writer team. Part I addressed what should be (but, unfortunately is not) simple and blatantly obvious. In this second and final paper, I want to discuss some specifics I’ve picked up over the many years about the many industries and businesses, and the many SMEs that make for efficient, productive SME-writer teams:

Image courtesy of chokphoto at

1)   It’s all about the people. Pick the right dude(s)/dudettes to be your SME(s).

I heard this from an anonymous runner after the Little Rock Marathon as finishers herded through a tunnel underneath the actual finish line:  This senior runner exclaimed in a boisterous voice, “It’s all about the people, baby! It’s all about the people!”

He’s spot-on, you know. It is all about the people. Hopefully, you’ve already contracted the best candidate for your project technical writer. Now you need to avail people who really know their portion of the project—really know it. And as I said, you need to avail them. Adding another task to an already oversubscribed person makes for bad mojo, man. And, it will affect the project deliverables, at minimum schedule and hours.

2)   It’s not about seniority or rank. Pick the right dude(s)/dudettes as your SME(s).

This seems repetitive to #1, or at least a sub-variant. But, it happens often enough that I thought I should call it out. I have worked for several clients whose SME was asking techs how they did this or that. Now, I’m not at all above asking questions—that’s integral to how I make a living! I’m just suggesting that if you’re developing a procedure for a specific process, such as changing out thermocouples or overhauling a valve, avail the tech who routinely performs that task to be the SME for that procedure.

I recently read an autobiography, Rebel Private:  Front & Rear! It’s the story of a young man from Liberty County, Texas, who joined the Confederate Army early in the American Civil War in and fought the entire war as a private, and returned to Texas after Lee’s surrender. It’s a fantastic historical account of the American Civil War through the eyes of a private. At one point, he was routinely reporting directly to General “Stonewall” Jackson during the heat of maneuvers and battles in the Shenandoah Valley of Virginia. Gen. Jackson made decisions that affected the lives of his men, the outcomes of battles, and even the war based on the reports of this private! The takeaway for us is that if Gen. Stonewall Jackson found the guy whose competence he could trust—some country boy private from East Texas—then we need to trust the right competent person to be the SME for whatever we’re trying to capture or document.

3)   Set the bar for the SME(s). Ensure that the SME understands the value of this effort to the mission of the organization.

This is another one of those “obvious” ones, but I’ve worked with a few SMEs who thought the process of capturing what they did day-in and day-out was stupid, or a colossal waste of time. It’s most likely a symptom of thrusting the job/SME title on them without getting their buy-in; but, the net effects, generally, are hits to production schedule (i.e. delays) and extra hours (i.e. cost). However, a bad start can also affect the technical quality or validity of the document(s), and will likely carry over into their limited usage and net value.

4)   Make the SME accessible. In other words, ensure that the writer has access—physical, email/phone—to the SME and vice versa.

What I’ve found is that oftentimes, working around the plant or shop is so commonplace for the clients, they sometimes forget to take the steps to make their SME accessible. For example, are there hours of operation when the writer cannot get to or through to the SME? Does the writer have the proper access? Does the SME need to come get the writer to escort him/her around the jobsite? Sure, some of these things are biggies and most writers and clients hammer that stuff out in the project contract. However, I have had too much downtime in my career not knowing if I could enter a certain place, or wandering around looking for my SME, or waiting on a response from the SME critical to the document’s development and validation.

For example, I was trying to wrap up a project to deliver a client’s 40 or 50 already developed procedures. The final step on the milestone schedule was to conduct a one-day to walk-through for all procedures as a final content validation (i.e. nomenclature callouts, document and tag numbers, photos, etc.); however, I showed up on-time and was locked out of the plant. The client was performing company-sensitive testing, so no contractors were allowed in; and the time to re-open was “any time now”. Meanwhile, the hours ticked by, but I had to wait on-site to complete the contract. Now, I certainly appreciate a client needing to conduct operations critical to their business. But, I also loathe inefficiency, and me being paid to sit on my duff and produce nada makes me cranky. Fortunately, I was blessed with several hours of remote work for another client that I was able to perform in a safe area on-site, therefore avoiding having to bill this client for my downtime, and then completed his project on-schedule when the plant reopened later in the afternoon.

Many times, I have been unable to locate my SME, and even more frequently, have had to “sit on” a document until I could finally get a response from my SME. Holding up production looking for or waiting on SMEs is so commonplace, it’s a joke among technical communicators. And, while completely solving this may be akin to solving world hunger, I think that clients are often oblivious to this phenomenon and how much it costs them in terms of project costs. And in a market characterized by cost-cutting and driving efficiencies, putting some emphasis on this area of your documentation project will invariably yield efficiency and reduce your document project cost. Again, it’s all part of setting the table for success to create a winning SME-writer team.


What’s in a Name?

Considerations for Defining the Naming System for Your Documents and Data

©2015 Mark Henderson

If I were a betting man, I’d lay a tidy sum on the side that most of you reading this have never given serious thought to how and what to name your documents. But, if I were to prove that the methodology you use to identify (and control) your documentation can have a significant impact—either positive or negative—to your bottom line, I might quickly move that wager to the other side—that you would consider your documentation nomenclature schema more intentionally.

Your system for document identification and control is your document nomenclature (or naming) system. In general, documents are often identified by their number and controlled by their version. Now, I said in general; that is because some organizations have a business need to assign ownership, and therefore control, within the document identifier. For example, all drawings are produced and revised by the Drafting Dept., so the document identifier—usually a numeric or alpha-numeric document number—might have “DWG” as part of the document identifier indicating it’s a drawing, and therefore owned (i.e. controlled) by Drafting. But, in general, when we refer to controlling documents, we’re talking versioning.

Versioning all documents is critical to managing documentation!

Rule #1 in versioning:  Do it! Rule #2:  Refer to Rule #1. Versioning all documents is critical to effectively managing documentation and maintaining any semblance of order and document integrity. Best practices for managing versions—or the cons of bad or non-versioning—is a discipline unto itself, and can be a standalone subject for a future whitepaper. I am only discussing the approach for identifying your document versions.

When defining version nomenclature, keep it simple—the simpler, the better. I prefer a whole number, such as 1.0; others prefer a single, uppercase alpha, such as “A”. Some like to add a date, such as a release or approval date. I disagree; I prefer adding document dates to document’s revision and history page, if for no other reason that adding a date to your version ID violates the “keep it simple” rule.

When defining version nomenclature, keep it simple.

That said, I certainly understand the need for identifying versions iteratively during development and validation (i.e. pre-release) phases. Wendy and I use iterative versions all the time—and I do mean all the time. As consulting writers, we denote deliverables in whole numbers, and iterative versions between us as 1.1, 1.2, and so on. Similarly, most businesses use the whole number (or alpha) to denote release or approval, and single decimals to distinguish iterative versions not yet approved or released. Software developers can iterate so frequently and so rapidly—especially agile development—they need a special approach for identifying versions, both for the software being developed and for the corresponding documentation. Most software development organizations have a system for checking out and checking in software that versions each increment checked out and in; user document development usually follows and is similarly versioned, oftentimes in parallel. What you don’t want is to have your versions looking like IP addresses, because it’s darn hard to figure out what version you’ve got when it reads something like v.! Again, emphasis should be on keeping the version identification simple, even in software development.

So when it comes to identifying, or naming, your documents, it probably will come as a surprise that absolute simple is not always the absolute best. It’s just not that simple, darn it! For example, if I identify the first document produced as “1”, and the second as “2” and so on (and that is as simple as it gets), how do I know if I have a drawing or a policy by looking at the document number? Or, next year, after I get “downsized” or promoted or brain-drained or gone, exited by any number of means, how will the folks left behind know how to search for this or that document? My point is that oversimplifying your document naming method can create inefficiency and errors (a.k.a. cost you money).

In naming your documents, simple is not always the absolute best option.

On the other hand, over-complication can create the same, or even worse. Usually, over-complication is the result of so-called “smart numbering” systems. In my opinion—after playing with about a gazillion documents spread throughout hundreds of different client nomenclature schemes—the more groups of IDs set between dashes, the “dumber” the number, and I have seen some dumb numbers!

I believe the minimum elements of a document ID should be the document type (e.g. DWG-, BOM-, PLAN-, PROC-, FORM-) followed by an alpha-numeric document number, and of course, the version. The number of characters in the document number should be dictated by the size of the organization and the number of documents envisioned, in total. When deciding to include additional information in the document number, do so judiciously, and with the knowledge that you’re adding complexity and probably not nearly as much value you think.

The ideal element of a document ID should be the document type followed by the alpha-numeric document number and the version.

One of the biggest problems I’ve found with “smart numbering” systems is they are more difficult to search in enterprise document databases/document management systems (DMSs). This costs time—often, lots of time when multiplied by the number of users in a large organization—and that is time wasted.

Documents need to be clear, concise, and valid; and, they also need to be easy to find. And search capabilities of the DMS aside, it’s the name (or document ID or number) that enhances the document’s ease of being readily located.

Documents need to be clear, concise, valid, and easy to find.


When Good Procedures Go Bad
©2015 Mark Henderson

I recently worked with a client to develop a large number of detailed task procedures. It was a great relationship and in the course of the contract, we developed about 400 procedures (initial release plus revisions) over a vast array of equipment and planned work activities. This was done largely in response to the client’s top management direction, that work would be performed using procedures and that people would be trained in their use.

Image courtesy of stockimages at

I would love to report that I truly believe the client will follow through and use those three or four hundred clear, concise, and valid procedures we delivered, and will realize the long-term benefits that come with enforcing discipline into any process. Casting no disparagement toward this client, I suspect that this story won’t enjoy this happy ending. This is because my observations lead me to believe that ingrained in their culture is a—to paraphrase that comedic movie western line—We don’t need no stinkin’ procedures notion that seemed imbued in the organizational belief system, despite what the top brass declared.

So, what happens when nobody uses what starts out as good procedures? In a nutshell, they “go bad”:  Configurations and nomenclatures change, processes change, “stuff” changes; but, the procedures never get changed. So, the people doing the work who already think procedures are useless sure aren’t going to use procedures that are obsolete!

So, what motivates an organization to change? And not only change, but change the organization’s belief system? It’s a tough question, and there are dozens of books written by experts on changing an organization’s culture, so I’m not going to portend to be an expert or try to answer that question. However, a former colleague with whom I had teamed on a Super Fund remediation project some years back opined that the only way some organizations change is when someone gets killed or when someone goes to jail. It sounds harsh, I know, but he was simply saying that changing an organization’s cultural belief system is difficult—so difficult that it rarely happens unless there’s an avoidable catastrophe that overcomes the inertia of years of entrenched mindset.

On the success side of the coin, I did a project for a heavy manufacturing firm not long ago. Even before I wrote the first procedure, they helped plan the format to allow them to repurpose the content into training materials; they also planned the process for revision in order to ensure the procedures would be kept up-to-date. But, more importantly, they positioned each procedure on the floor with the technicians executing that work, making access easy. Then they trained every employee on every procedure, and they enforced the usage of these same procedures as condition of employment. These guys were serious about operating the old ISO adage:  Document what you do, and DO what you document.

During a follow-on contract to develop lock-out/tag-out procedures at that same facility, I witnessed firsthand the way this company walked the walk as well as they talked the talk:  Whenever they wanted to improve a sub-process, they accounted in their planning for the changes required to their released procedures. I walked away from this client knowing that the clear, concise, and valid procedures I delivered initially would not only be used, but would be kept clear, concise, and valid (or at least the valid part) long after I was gone. This enterprise got it:  They realized that to keep their processes in control, they needed people executing their work the same way across shifts, day in and day out. To do that, they needed to document the processes the way they should be performed, and then update the procedures to reflect process improvements. This would keep their processes in control, and keep them on the road to continuous improvement.

In conclusion, I think it’s fair to say that to bring a process in control, the process must be documented and the documents must be used in process execution. So, when organizations invest in documenting processes with clear, concise, and valid procedures, it seems shortsighted or even foolish not train their folks on their application and use (to steal a page from a former client’s top brass edict), as well as to enforce their usage when performing those work processes. It seems similarly foolish not to update these procedures as things or even the processes change (such as continuous improvement). Or, to say it another way, to allow good procedures to go bad!


Why the OEM’s Manual Might Not Be Right–At Least For Your Business

©2015 Mark Henderson

“Why, if I had a nickel for every time I heard that….” is the perfect cliché’ to introduce this topic. Seriously, I wish I did have that giant truckload of nickels as often as I’ve heard this saying—a.k.a. “roadblock”—for creating clear, concise & valid documentation:  Why would we rewrite the instructions that the original equipment manufacturer (OEM) wrote for the thingamajig it built that we’re using in our business?

Fair enough—it certainly sounds like common sense at first blush. The implied corollary is:  “What value could we possibly add to what the OEM wrote for the equipment they designed and built?” Well, the answer may be “None”, as far as how that OEM manual or OMI or user’s guide is used in your business. But, if your business were my business, I would want to look at every tool I use—to do whatever it is I do to make profit—in order make darn sure that it’s (a) the right tool, and (b) being used the right way. In many applications, the OEM-provided information (e.g. manual, user’s guide, OMI) is a tool for me and my folks to do whatever it is we do—safely, efficiently, and of high-quality. So, how do we exercise our due diligence to ensure we are using the right stuff the right way?

What value could we possibly add to what the OEM wrote for the equipment they designed and built?

Well, we first start by reading the OEM document(s). This is just from my personal experience, but many of the folks who utter the “We just use the OEM book and we’re not going to improve on that…” line remind by of CEO Frank Shirley in the film Christmas Vacation when he growls to Clark Griswold (Chevy Chase), “And don’t bother me with all that techno-mumbo jumbo either!” Many times, the OEM document is foisted upon the technicians or programmers or whomever is actually doing the work by persons who have never even cracked the book.

After reading the OEM documentation, there are two similar, but different questions to ask:  (1) “Is it good (or good enough)?” And (2) “Is it good enough to use for our purpose—the way we need to use it?” If after reading the OEM documentation and the answer to those two questions is “yes”, then there is no ROI to reproduce this in your company format.

Is the OEM documentation good enough, and is it good enough to use for our purpose—the way we need to use it?

However, in my line of work, I read ullottuv (i.e. piles, scads, tons, bunches, etc.) of OEM technical literature. And if you’re one of those whose job it is to try to use OEM technical documentation to accomplish your task, it will come as no surprise when I say that I find less than a third—maybe even less than a quarter—of the manuals or user’s guides I’ve studied to be even marginally comprehensible. Everything from the order in which the information is presented to the logic used in ordering the information to the actual words used, most OEM manuals are of little value to the actual users. In fact, most techs I work with use OEM documentation the first time the thingamajig is used. After that, it’s “tribal knowledge”, or this guy teaching the next how to do this or that to said thingamajig. And most of these folks are executing their tasks under some statement or requirement to utilize the OEM’s data to perform their work. Now, this is no way a lick on the techs—rather, it’s a testament to good people who will somehow find a way to make things work in spite of inadequate documentation!

Most OEM manuals are of little value to the actual users.

So, casting the above anecdotal information aside, let’s say the documentation you received from the OEM is high-quality, sensible, well organized, and technically valid. But, is the OEM documentation everything you need for you and your team to perform your tasks predictably and safely? Is it sufficient the way your team uses the thingamajig? Ask yourself, “Are we giving our people the best tools we can to accomplish our business’ mission?”

Make sure that we give our folks the best tools to do what they do.

Maybe we should reject the Mr. Shirley philosophy and go read all that “techno mumbo jumbo” to make sure that the tools we give our folks to do what they do to make our business profitable are the best tools—that the documents we require them to use are clear, concise, and valid for what we do—so they can do the best job we’ve hired them to do.


Information Overload

©2015 Mark Henderson

I made a faux pas the other day:  I had gotten off the elevator at a client’s building, leading—with legs that are always aimed somewhere and moving fast—a group to a meeting. Being first to reach the doors, I grabbed and inadvertently tried to rip the thick-glassed door off the hinges, and with a loud shuddering boom, I might add. The group behind seemed to gasp in unison, “DON’T YANK ON THE DOORS!” Their collective tone seemed to add “idiot” as a closer, but no one actually said it, audibly anyway. Of course, there before my eyes was a fairly bright placard on the very same door that read (as best I can recall), “PLEASE! Do not force the door open. Sensors will release the lock…” It went on to describe that these doors have been damaged by—and these are my own words here—other knuckleheads who refuse to read signs. I was embarrassed, and my quick-draw arms requested my legs to slow down the pace, so I took a backseat to the group for the remainder of this little trek.

Of course, I could chalk this up to the Caveman gene rearing its John Wayne head. I was, after all, leading a group of mostly female peers and my inner Caveman wants to lead the way. I mean, there could be a saber-toothed tiger, or a whacked-out terrorist, or a glass wall all of which might need a little beat-down. However, upon further review, I came to the conclusion that I “missed” the sign—in effect, a mini-procedure—because of information overload.

Much has been written about this fairly new phenomenon:  In an age where we are continually bombarded with rapid-burst information, “information overload” dulls our senses, slows our abilities to process information as rapidly as it streams at us, and requires the use of mental “filters” to screen out chafe. Studies are revealing that our brains are being rewired to survive this information battleground.

So, what does this mean to those of us who need to deliver clear, concise, and valid (a.k.a. meaningful, useful) information?

Most importantly, I think, we need to be creative in the how we present information. How do we make it “applicable” to the receiver? Then, how do we make it effective? Advertisers are, as a group—and this is not a new phenomenon—well ahead of the curve on how to present information effectively.

Trust me, I would gladly have received the information, processed it as “applicable” to me, and followed the procedure for operating that door in the lobby. However, that procedure failed to communicate its important message in time for me to take the proper action.

The message is simple:  To be effective communicators, we must adapt our approach in this ever-changing information battlefield to create and deliver information that is both meaningful and valuable to our target audience.


ROI: The Case For Investing in Your Business’s Documentation

©2015 Mark Henderson

There are as many business platitudes as there are businesses:  Focus on safety; focus on quality; focus on improved sales; focus on the environment; focus on small, furry animals. You’ve heard most of them before. Well, maybe except the “small, furry animals”—that was a freebie. But kidding aside, while all of these platitudes share a universal appeal, they are all really a focus on the business’s bottom line, or profit. Workplace injury (or worse) costs a lot, as do having to recover quality, losing sales, or sullying the environment. And while each of these profit-sucks may have obtuse root causes requiring unique solutions, documentation is and will nearly always be the common denominator.

Lack of clear, concise, valid documentation is and will nearly always be the root cause of profit loss.

Unfortunately, many businesses fail to place high enough value on having clear, concise, and valid documentation for whatever it is that their business does. Documents that codify policy, plan executions, execute processes, or instruct users how to install, use, or maintain the business’s product are often hurriedly thrown together; and, too often, by people already over-subscribed with too much work, whose primary skill in the organization does not include the descriptor “Writer” anywhere in their job profile.

People already oversubscribed with work are often given the task of “writing” the company’s documentation.

Still, that is better than some businesses that seem to embrace the adage, “Documents? We don’t need no stinkin’ documents!” As a consulting technical and business writer, a large percentage of my clients over the years have fallen somewhere in this camp; that is, until something went terribly wrong, and I was brought in to help.

So, why invest in documentation? As were the plethora of root causes to those big-hitter profit-sucks, the reasons to invest in developing clear, concise, and valid documentation are, likewise, numerous.

So, why invest in documentation?

For example, task procedures can enhance safety, improve process or product quality, reduce risk of an environmental incident, and reduce the impact to the organization from an external audit. Of course, a business’s process or product quality will inevitably have an impact on sales, but an enhanced safety and environmental posture can also improve sales.

Task procedures can enhance safety, improve process or product quality, reduce risk of an environmental incident, and reduce the impact to the organization from an external audit.

There is a reason that the top quality standards (e.g. ISO, API) require organizations to “Document what you do; and do what you document.”

Another reason to invest in developing clear, concise, and valid documentation is to free up the people being paid to produce whatever it is your business does to produce whatever it is your business does!

Clear, concise, and valid user documentation (e.g. users’ guides, OMIs) improves your customer’s satisfaction and reduces unnecessary customer queries or requests for assistance.

“Document what you do, and do what you document.”

I’ve provided a few high-level examples to support the ROI case for investing in your documentation. And for brevity, I haven’t even touched on compelling web content driving sales, or cogent responses to RFPs acquiring contracts.

The case for investing in developing, using, and maintaining clear, concise, and valid documentation is simple: your business’s documentation will provide a return on that investment and, in the end, improve profit.