Post History

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

As noted in [this answer](https://writing.stackexchange.com/a/36511/1993), you do need to be mindful that for a user guide your reader's goal is _information_, while for a rulebook it can also be _entertainment_. If the entertainment gets in the way of the information, the reader who has to finish his task _today_ and is stuck on how to do the next step is going to be frustrated. There is room for entertainment (including humor) in technical writing, but it **must not be on the critical path**.

A technique I've seen is to use "sidebar" examples with a common thread. I say "sidebar" because they're visibly offset in your layout (like in boxes), a style that's also used for game rules. Also like with game rules, you establish the scenario and then progressively build on it over the course of the book. The main body of the text must never _depend_ on these examples, because there's context in that earlier setup that would be too much work for somebody who's just trying to configure his frobbitz and needs to understand the thingy parameter, but the example is there for somebody who (when not pressed for time) wants to see a complete scenario. A corollary is that these "sidebar" examples should not be the only examples in your user guide; show essential examples "inline" like you normally would. The "inline" examples demonstrate the particular function in as much detail as is needed; the "sidebar" examples show _one_ way that all of these pieces fit together.

Original score: 7