Post History

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

I agree with @mbakeranalecta that the purpose of tecnical writing is not to entertain but to inform.

I recall a textboook on software development that I had in college where the text was regularly interrupted with little stories about "Sally's first day as a programmer" and the like. These stories were presumably intended to liven up the text while illustrating poings from the chapter. Personally, they just made me feel embarassed for the author. The stories were not only mostly irrelevant, but lame and cloying. "Oh, how exciting it is to work in the real world of software development! Sally exclaimed." It was just dumb.

That said, I think it can be good to break the tedium of dry material now and then. I wrote a database book where I got a cartoonist to draw some cartoons for me that I THINK were not-stupid, maybe one for every chapter or two. I wrote a user's guide once where in the section describing how to add and delete users from the system, I introduced the section on how to restore a deleted user by saying, "If you delete a user, and then they come crawling begging for their old job back, you can restore the user by ..." Okay, not the sort of joke that will have people roaring with laughter, but I figured it was worth a chuckle and helped lighten the mood. I think that sort of thing is helpful.

But I would be very careful not to overdo this sort of thing. One little joke every ten pages can lighten the mood. Even if the jokes aren't very good, the reader probably won't mind. It's a break. But if you do it constantly, readers are eventually going to be saying, "Hey, I'm trying to learn how to operate a Foobar, not hear a bunch of your lame jokes."

Original score: 4