Post History

Source: https://writers.stackexchange.com/a/35032
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

There are two issues here. One is whether technical documents should include "creative" language. The other is whether problems with style should be fixed despite looming deadlines.

On the second point -- assuming that whoever is responsible has decided that there is a problem with the document -- it stands to reason that you should fix as much as you can despite the looming deadlines. Presumably you expect people to read this document. If 50 people read it, and a problem causes each one of those people to waste 5 minutes of his time before he understands what he needs to understand, than you have wasted 250 minutes or over 4 hours. If you can fix the problem with less than 4 hours of editing, then it's a net gain. Fix it.

The bigger question is whether technical documents should include creative content.

An anecdote: At a staff meeting once, someone commented on how great the technical manual was for some new software product the company had just bought. Easy to read and understand, clear examples, and humor sprinkled throughout to keep it interesting. Everyone agreed this was a great technical manual.

At the next staff meeting, we were reviewing a draft of a technical manual that I had written for a product that our company was developing. I took a lot of criticism for using simple language and including humor. (Perhaps I should clarify that by "humor", I don't mean I inserted irrelevant jokes, but rather that I kept the tone light. Like when describing a delete function, instead of saying "when you need to delete a record", I said, "If you discover that you've made a horrible mistake and you need to delete this immediately". Not roll on the floor laughing hysterically humor, but light touches here and there.) Several people said this was "unprofessional". I pointed out that just a week before they were all praising a tech manual for doing exactly the same thing. "But that's different", they said. In the end they changed all my humorous comments to be deadly serious. changed every place that I wrote "use" to say "utilize", changed short simple sentences into long complex sentences, etc.

When people are READING a technical manual, they want it to be simple and straightforward and easy to understand. But when people are WRITING a technical manual, they often want it to be pretentious and deliberately difficult to understand. Because many people think that the goal when writing a technical manual is not to teach the reader what he wants to know, but rather to impress the reader with how smart the writer must be to understand this incredibly difficult and complex subject.

In my humble opinion, the best manual is one that leaves the reader thinking, "Oh, this is all very simple and obvious. I probably could have figured it out myself without bothering to read this." But many writers want the reader to walk away thinking, "Wow, this subject is very complex and baffling. Even after reading this book I don't understand it at all. The writer must be a genius to understand this."

But all that said, if the boss says, "keep it deadly serious and ponderous", you can try to change his mind, but if you fail, well, he's the boss and if you want to keep your job you're going to have to do it his way.

Original score: 2