: Should creativity or eloquence in a technical document be removed during review? I am working on churning out some technical documents, which are similar to a colleague's. I've copied some sections

Vote Up Vote Down

IMHO the answer depends on what kind of technical document we are talking about.

In a free-form document (like an article, tutorial or comparative analysis), there is room for creativity and eloquent language.

In a reference manual, everything should be straight to the point. Extra creativity can only distract the user and create ambiguities.

(0)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

This is a supplement to this answer.

Readers, especially technical readers, notice small variations and especially inconsistencies. If you talk about "removing" a resource in one place and "deleting" it in another, some but not all readers will think that's two different operations. This problem is amplified if your documentation is translated into other languages, because now both the translator and the reader have to interpret your subtle variations.

You can minimize this confusion by consistently using the nouns and verbs already in use in your documentation set. (When something is different from a similar-seeming one, call it out explicitly.)

This does not mean that there is never room for humor or even whimsy in technical documentation. If it is not unusual in your domain, you can sometimes be more creative with your examples. Never do this at the cost of clarity, but, for example, you can do this if you need to show some sort of user workspace and the actual content doesn't matter. If you're showing how to lay out a circuit board and your audience is expected to be geeky, it's not wrong to name the project in the screenshot NCC-1701-replicator instead of circuit-2. But don't do it if there are 500 examples in the documentation and you're just changing this one; be consistent in your style throughout the documentation set. I've found that "whimsical" examples are best reserved for shorter, less-formal, stand-alone documents like blog posts and use-case descriptions.

(0)

Vote Up Vote Down

The goal of a technical documentation is to tell the reader what they need to know to continue working. They are not interested in reading a nice play on words or particularly interesting ways to phrase something. They are looking for a text that's easy to parse so that they can find what they are searching as fast as possible.

With a novel or something similar you are looking to entertain yourself. When reading you just want to read, you want to get absorbed in the world that someone else is describing there.

With a technical documentation you are looking to find some information that helps you to continue your work. Maybe you don't know which steps to follow to restart a service. In that case you don't want to read something about the ideas that went into the design of the UI or the processes that led to the decision to put Button A to where it is - you want to read the steps to restart your service. And you want them now. Because you need them now. Every minute that you spend reading something creative is a minute of work time lost and potentially a minute of downtime.

The guidelines are there to ensure that even critical problems will be solved as fast as possible. Your specific problem may not be that critical, but some problems are that critical, which leads to such guidelines.

The next thing to keep in mind is that you should try to write in a way that is easily understood by everyone who is familiar with the context. If there is a certain style to technical documentation in your company then you want to adhere to that style so that everyone who knows something about technical documentation in your company can parse your document as quickly as possible.

That means that you will often have to introduce a way to phrase certain things that may feel a bit unnatural or clunky from a creative perspective. But by having these standard phrases it's easier for others to decide whether that paragraph is important to read.

People who read technical documentation rarely have time. And they never have enough time.

That's why it's important to write without any creative sections, even if the deadline is approaching. Because if you fail to fix these things that are not-really-problems-just-differences-in-style then you can be sure that someone will trip when trying to find something important in one of your documents at one point. And every minute may count in such a case.

(0)