Here’s some authentic, historical pre-computer, pre-calculator thinking. In the 1970s, when four-function calculators first became widely available, users fell into two camps. Some, mistrustful of their skills, still calculated in their head but then checked their answer with a calculator. Others, mistrustful of the calculator or their ability to enter data correctly, used the calculator first but then checked its answer in their head. To this day I am in the second camp. This is partly a legacy of my academic course of studies: always check the units and the order of magnitude. (In cosmology, if your theory was right to within an order of magnitude, you were on the right track.)
This stubborness has a place in technical writing today. It’s not refusal to accept new technology or new facts, but rather refusal to accept things at face value. You may not be able to confirm that something is right, but you can check that it makes sense. I call this validation of plausibility. As President Reagan once said to Soviet arms-control negotiators: trust, but verify.
I draw a distinction here between copyediting, or applying company branding, copyright, logo, and style guide rules—all necessary checks expected even at a low skill level—and validating plausibility. It’s easy to point out a typo or an incorrect product name, and that level of vigilence is expected. But for a new practitioner, technical input from subject-matter experts is like the received word of God and not to be questioned. Well, here’s a secret: we are all human. Software engineers copy and paste code where they shouldn’t; accountants mess up the books; lawyers make typographical errors in laws; doctors write incorrect (or illegible) prescriptions. We know this applies to everyone in all fields. And yet it takes time and experience to reach the point of not accepting input you’re given at face value. Applying experience, logic, and common sense can help you recognize when some fact you’re given might not be—or even definitely is not—true.
There’s nothing wrong with a technical writer double-checking the plausibility of information. (Call it a “sanity check” if you will.) Most of the time, everything checks out, and no one needs to know you did it. When in doubt, ask. If you point out something that doesn’t add up, you just might find yourself a hero.
Don’t believe everything you read
Here’s an example. Let’s say you work fort a smartphone manufacturer and an engineer wants you to add this statement about a new product to the corporate website:
When meassured as a standard rectangular shape, the xPhome 15 screen is 6.35 mm diagonally.
I would expect even a new practitioner to fix the typo “meassured” without asking for permission or approval; that’s purely in the writing domain and no one will push back. Some would stop there, but an experienced practitioner should also notice the product name “xPhome,” double-check it against the product name list, and, if it’s wrong, question it. That’s a product-name issue with a defined right answer, and this is probably a typo for “xPhone.” Job well done, everyone! But… Is that screen size plausible? It’s a technical detail, so how dare I question it? Well, ask your digital assistant: Siri tells me that measures a quarter of an inch. The new phone model has a diagonal screen size of a quarter of an inch? No, that’s not plausible. Something—the number, the decimal point, or the unit of measurement—is implausible.
(Aside: I took a real website footnote and introduced those three errors; the actual text is clean, and the unit of measurement is inches. However, if I worked there and had had a second cup of coffee that morning, I might also have asked why the dimension was given only in inches, not inches and centimeters, as appropriate for a multinational corporation.)
Here are examples of things to look for:
- Hardware: Do the weights of the servers in the rack add up correctly, and is the configuration overloaded? Is everything given in US voltages or European voltages, as appropriate? Is the top speed of the aircraft in the range of a jet fighter, a dump truck, or a flying saucer?
- Software: Is a file listed but not described? Is every function name spelled correctly? Is the set of code or error messages parallel in structure (address space) and without duplicates? After you’ve documented 200 APIs grouped into sets of CREATE, DELETE, SET, and SHOW calls, is a new block with the calls ADD, KILL, CHANGE, and VIEW correct? (This last is for extra credit. When it happens, the developer is usually new and unaware of established convention, and the software architect will be very unhappy if that convention is disregarded.)
- Medical: Do the percentages of study patients who experienced side effects match the actual numbers? (I wouldn’t touch the statistics but I can add.)
- Financial: Spreadsheet formulas aren’t infallible. An accidental change to a cell can break the entire sheet. Spot-check the math and you can be a hero.
When you think you’ve spotted an implausibility, don’t be afraid to politely ask about it, but be humble. The first time you think something is wrong, you’ve only attained the “a little knowledge is a dangerous thing” level. Going in guns blazing and announcing that the chief architect made a mistake is poor tactics, potentially embarrassing, and possibly job limiting. Asking a polite question is a far better approach. For example: “Our documentation says the average transaction takes twenty milliseconds. You said here that you have reduced transaction times by twenty-five milliseconds. Isn’t that impossible?” Obviously it’s a mistake, but what? If you confront the person with an error, nothing good is likely to happen. Phrased as a humble question, it gives the chief architect a graceful, face-saving exit: “Of course, I meant 2.5 milliseconds;” “I should have said twenty-five nanoseconds;” “I was speaking of the slowest transactions, not every transaction.” Saving face is more important in some cultures than others, but it’s at least a consideration everywhere, so adjust your approach to the personalities involved.
Do your homework first
There’s a fine line between being curious and asking others to do your work for you. “Are you sure these numbers are right? You should double-check them” is making work for someone else. If you don’t think they’re right, you check them. Don’t assume something you don’t understand is wrong—you may simply not understand it. Do your research first! Then you can ask questions.
Verifying information to the extent that you can, and questioning implausible input, is a technical communication best practice. Over time, as you develop domain knowledge at your job, you will understand more, ask better questions, and spot implausible input more easily. But this practice itself is portable, and you can apply it to any field.
The effect of catching technical errors is to give your team the impression that you are competent, thoughtful, and thorough—all facets of a great professional reputation!
Steven Jong 