I recently had to oversee the introduction of a custom-built IT system in an industrial environment. A few in-jokes in the manual went over quite well during training. They were along the lines of using the name of a known computer-illiterate person to illustrate log-in or listing example orders that would never get through the management.

However, in this example, 1) the humor was completely tangential to the technical message, no words were spent on it, 2) it was subtle to the point of deniability, 3) it was specific to the audience - letting them feel clever for getting the references.

Under such circumstances, I've seen such subtle humor to work. Otherwise, there's no room in technical documentation for it. It's better to provide brevity. In my experience, the problem with tech writing isn't the lack of humor, but the excess of repetitive formalities and passive voice.

I recently had to oversee the introduction of a custom-built IT system in an industrial environment. A few in-jokes in the manual went over quite well during training. They were along the lines of using the name of a known computer-illiterate person to illustrate log-in or listing example orders that are impossible to carry out for non-obvious reasons.

However, in this example, 1) the humor was completely tangential to the technical message, no words were spent on it, 2) it was subtle to the point of deniability, 3) it was specific to the audience - letting them feel clever for getting the references.

Under such circumstances, I've seen such subtle humor to work. Otherwise, there's no room in technical documentation for it. It's better to provide brevity. In my experience, the problem with tech writing isn't the lack of humor, but the excess of repetitive formalities and passive voice.