The finance department at a major energy company had a big problem. John, the most senior accountant, was preparing to retire.
John knew everything that went on in the department. The trouble was, there were parts of the job that only John knew about. There was a big concern that once John left, there would be gaping holes in the daily and monthly processes.
What can you do in that situation? Well, normally you might ask John to just tell his co-workers what he does. He might write up a series of documents detailing his normal processes. He would then sit down and explain the documents to the people who would be taking over the different parts of his process when he left.
The trouble was, John had trouble communicating what he did to others. First of all, he was too busy to spend much time writing. And when he did finally sit down to write, he would put together big, confusing documents. The documents would ramble here and there and everywhere, while leaving out massive amounts of necessary information. John was a true expert, and so he assumed those he was writing for would know what he knew.
How bad it can get
But who would be using John’s documentation, actually? Probably not an expert at the level of John himself. Most likely, it would be a newer employee, perhaps a younger employee.
It’s always tough when an experienced employee leaves the company. But it’s especially difficult when dealing with the new generation of employees. Younger accountants and CPAs, along with their peers in other industries, have different priorities than previous generations. They are not as likely to stay with one company for many years. They come in and learn and leave. So the brain drain is even more extreme than it has been in the past.
So when you hire a new employee, it is more important than ever to be able to get them up to speed quickly. Otherwise, knowledge from the previous generation of CPAs will be lost, and the new generation will have to relearn the same information and lessons over again.
What to do about it
Follow these steps to make sure that you capture needed information from employees before they leave:
- Think ahead. Before you get down to actually writing the information up, you need to do some prep work. This will ensure that you get the maximum benefit out of the effort you’ll be undertaking. Be sure to cover the following:
- Recognize that information is a critical business asset. The information that your employees possess is what makes your business run. If that information gets up and walks away, you’re sunk.
- Prioritize the most critical information. When any of your employees leave, it can be a blow to the business. But you and I both know that some information is more important than other information. Think about the critical processes in your business, and who makes them go. If Jack retires (or gets sick for a while), does anyone else know how to make sure the invoices are handled properly? If Maria, who is the only person who knows how to make sure the XYZ balancing process is done correctly, is suddenly out of the picture, what kind of damage would that do?
- Communicate the need to employees. You need to emphasize how important it is to capture how your employees do their work. Make sure they know that you’re not trying to replace them, or play big brother. Actually, you think they’re so important that you have to write down what they know. That way, you’ll have an insurance policy of sorts if they ever do check out.
- Prepare to allocate resources. The people who know your business or department the best are the ones that will need to devote time to the documentation effort. Make sure they know that they will be expected to contribute. At the same time, recognize that they may need to push one or more of their current duties to the back burner for a bit to make time to work on documentation.
- Get organized. Once you’ve gotten your vision straight in your head, it’s time to plan the execution. Use the following guidelines in deciding how you want to document what your employees know:
- Decide whether you will complete the writing in house, or if it’s a better idea to get outside help. Whichever option you choose, make sure your writer is an expert at communicating financial information. They should also be skilled at writing in plain English.
- Think beyond just creating or revamping a few documents. You will get the most value if you set up reviews, deadlines, and future revamps in an efficient way. Merely creating documents per se isn’t enough. You need to think about how the documents will be put together step by step, and how they will be distributed. Someone who is trained to communicate technical information can help with this.
- Involve writing resources early. Whether you use an inside writer or outside help, make sure they’re involved as close to the start of the planning process as possible. If you’ve already set up the project goals and organization, and you’re just now telling the writer you want their help, it’s too late. You won’t get as much value as you should.
- Get it done and follow through. I’m not going to lecture you on the principles of project management. If you’ve completed steps 1 and 2, step 3 should be simple. As always, be quick to communicate, and hold people to doing what they say they will do. Then make sure to follow up with any periodic updates or reviews that you schedule.
By following these 3 steps, you can capture the critical content that exists in the brains of your employees. This will help you minimize your losses when an employee leaves, and get the remaining, or new, employees up to speed quickly.
I recently presented this content at a meeting of the Greater Houston Chapter of APMP.
To see my presentation, you can review the SlideShare here.
We all know that, when it comes to a technical documentation, content is king. If we don’t have good, accurate, complete content, our documentation will fail. We can nail the grade level of the writing, and have excellent organization. However, without excellent content, those things are meaningless. Content is the King.
But at the same time, we can have great content that fails. In those cases, King Content is deposed, overthrown by issues that should never come up in the first place.
So what are the problems that ruin good content? Who are the plotters that overthrow King Content, and put the focus of our writing exactly where it should not be?
1. Overly complicated writing
A quote from Warren Buffet’s preface to the SEC Plain English handbook:
“Perhaps the most common problem, however, is that a well-intentioned and informed writer simply fails to get the message across to an intelligent, interested reader. In that case, stilted jargon and complex constructions are usually the villains.”
We must always ask ourselves a question when we read any technical document. That question is: “Did I understand this the first time I read it?” If a user will not understand the sentence, paragraph, or document the first time they read it, then you’ll probably lose them.
Now, it’s one thing to read something that someone else wrote, and identify some issues. But what if you wrote it yourself? Just about anything you write will make sense to you, since you’re the one who wrote it. And putting a document away for a couple of days isn’t a luxury we always have.
So what do you do? Use metrics. If you’re using Microsoft Word, then this is easy. Just enable the readability statistics add-on for the spell checker. Then you can review anything from a single sentence to an entire document, to see if it contains an appropriate level of complexity.
For the steps involved in enabling readability statistics, see Microsoft’s article on the subject.
2. Vendor-focused writing
“One the biggest problems with the text in proposals? Talking about your own company WAY TOO MUCH! The focus should be on the client. I try to use the rule of using your clients’ name three times more than your own.”
Proposal Writer at RTL Networks, Inc
It’s easy to slip into the habit of focusing on our own company, or our own technology. For documents that are aimed at a particular client, we may wind up talking about our company and its solutions much more than we discuss the client and their needs. Oil and gas companies may focus on their equipment or services, and forget that the client doesn’t care about those things (they only care about their needs). Software companies may produce documentation that delves deep into the inner workings of their product, but that doesn’t address how the features actually meet the customer’s needs.
What do we do to resolve this problem? First, count.
How many times in the document did you mention the client and their needs, versus your versus your own stuff? If the ratio isn’t at least 2-1 or 3-1, you may have a problem.
We can skip a lot of the problems associated with vendor-focused writing if we’ll take the time to plan the focus of the documentation up front. If we’ve decided as a team not to focus on ourselves, we’ll be more likely to wind up with the right result in the end.
But what if you have already received a document that is obviously written in a vendor-focused way?
You’ll need to perform triage. You need to know which sections are most important in the document. Is the most important section the executive summary? Is it the introductory content? Is it a key procedure midway through the document? Identify the key sections, and make sure they’re as client-focused as possible.
3. Glaring text errors
“Do not tolerate any mistakes.”
Elite Documentation Employee Standards
This one is pretty simple. You can handle it by reading over the document, and asking “Does any of this make us look dumb?” And “Which typos might make us look the most dumb?” Again, prioritize, and focus on sections and types of errors that could do the most damage to your company’s professional credibility.
Using a different set of eyes really helps for this one. I’ve become a very good writer, but I’m not God. My writing is almost never completely free from errors. No one’s writing is divine.
4. Schizophrenic writing
“Different authors may yield different styles or voice. These differences may also manifest themselves with the facts … Somebody has to do a “horizontal alignment” check.”
Principal at A&M CoOp
If you start encountering a lot of different voices in your technical documents, you should ask yourself, “Do we have a pre-existing standard?” When deadlines are looming, it’s not the right time to come up with standards. The right time to come up with writing standards is before the project even kicks off.
I remember working on a $1.5 billion proposal a few years back. I fielded question after question about what the “right way” to format something was. I helped the team come to consensus, but I couldn’t help wondering to myself, “Why are we just asking these questions now?” Companies need to have a style guide before writers even start working. Otherwise, decisions become very haphazard.
It also helps to have a rational workflow. To explain what a rational workflow might be for your company, let me explain the different kinds of editing that your documents need. (Keep in mind, I’ve written some of the following information from a proposal writing perspective. The workflow you use in your company might be much different. The important thing is that your workflow makes sense, and produces good results.)
Once you’ve gathered your content, it’s time to do a substantive edit. The substantive edit is different from the proofread in that a substantive edit asks the question, “Does this really make sense? If not, how can I rewrite this sentence or section or table header to make sure it does make sense?” Of course, depending on the volume of work that you have, you might not be able to do a substantive edit on all of your content. You need to prioritize which sections have to make sense. Then focus on making sure the writing in those sections is crisp and clean.
After the substantive edit, it’s time to proofread and copy edit. This will be relatively quick easy if you have a good set of standards. If you don’t, people will continuously make adjustments based on their own preferences. That will reinforce the schizophrenic voices that you are trying to silence.
5. Embarrassing boilerplate
“Nothing says “I don’t give a fig” like calling the customer Acme Manufacturing when their name is Amalgamated International.”
Head of Bid Management at Bull Information Systems
If your documentation projects tend to be similar, but not exactly the same, for each customer, then you may have seen some embarrassing boilerplate. (Boilerplate is text that is reused over time for multiple clients or projects.)
If you use boilerplate, you must ask yourself, “Which parts of this document will I need to customize for this customer?”
You need to have a list of the places in each document where you need to customize the information. You don’t want to get in a crunch, and then have to search frantically for each instance of text that refers to a different customer. You won’t find everything, most likely.
For this effort to make sense, you also must have a good style guide, with standard terms your employees should use. This will help you with global searching and replacing, especially in Microsoft Word. If you refer to a customer as ACME, ACME Inc., ACME Amalgamated Inc., and ACME incorporated, you will have a much harder time getting everything updated.
Boilerplate tends to hurt the quality of many kinds of documents. But in the software industry, and in certain industry niches, boilerplate is critical.
May this this article help your content grow stronger. Long live King Content!