I recently ran a work report that provided a list of diagnostic descriptions within our application. These diagnostics are stored in a database table, and they appear when an issue is encountered within the application. They provide an error code, a description, and a recommended course of action.
I was running this report so I could document the application used to generate the report. But when I looked at the results, something struck me.
There were sixty-one active diagnostics. Looking down the column containing the recommended courses of action for each diagnostic, something stuck out at me like a sore thumb.
In EVERY SINGLE action, the first word was “Please.” Every single action started with “Please ask…” or “Please perform…” or “Please do this…” Every. Single. One.
I was raised to be polite. My mother always taught me to say “please” when asking for something. For the most part, I agree with this. All children should be taught to say “please” and “thank you.”
That said, this is not appropriate in most professional-level technical communication.
When you’re writing technical instructions, you are telling someone how to do something. You are NOT asking someone for a favor!!! This is another one of my technical writing pet peeves. Writing professional technical instructions involves using language that’s direct and to-the-point. Unless the tone of your document is laid-back or colloquial (the “For Dummies” series of books comes to mind), it is NOT supposed to be conversational.
Now, I’m sure a number of people reading this might not agree. It should be pleasant to read, you might say. Here are the reasons why I don’t agree.
Instructional language should be neutral. See what I wrote above. I’ll say it again: you’re telling someone what to do, not asking a favor. You’re trying to get your reader to complete a task, not trying to make friends with him or her.
It’s extraneous. One of my tenets of writing instructions is that it needs to be as simple as possible. In my documentation presentation, one of my major points of emphasis is the KISS principle. A big part of keeping it simple (which, granted, isn’t easy) is to eliminate anything extraneous. Extra words add complexity. The less complexity that’s in an instruction, the better.
It’s annoying. When you’re reading a set of instructions, reading “please do this” and “please do that” gets old after a while. I’ve read instructions like that before (including the report I describe at the beginning of this article), and by the time I got to the end of the document, I wanted to slap the writer more than I wanted to finish the task.
When you’re having a conversation, saying “please” is very much appropriate. But technical writing is not a conversation. Conversational language is not appropriate in professional technical writing. As a technical writer, I’m imploring you: please stop saying “please!!!”