4

I'm increasingly having to write User Guides as part of my job and I need routes to make this into a more interesting exercise.

Hence, I was actually looking for something completely different when I started writing this question such as 'can I use humour in technical writing?' but found that this had already been asked (How much humour is effective in technical documentation?) with the answer being a resounding no (aside from X for Dummies books).

So then I was thinking about asking a question like 'Can I make User Guides more engaging?. I was beaten to the punch by this engaging question: Can technical writing suck less. The answers this time were along the lines of 'yes, but not with humour'.

And then I saw this (from Michael):

One example that sprung to mind is the instructions or "rules" for games. Some of these books can be so engaging that a lot of fans just read the rulebooks without actually playing the games (I know I have, and I notice people on discussion forums for e.g. roleplaying games reporting the same fascination).

And this led me to wondering about writing rule books that are so entertaining that they are capable of being read in much the same way that stories are. So, here (finally) is my question: How challenging would it be to rewrite a (random) User Manual as a tale of derring-do and intrigue? In other words - what would be the best technical approach to rewriting a User Guide as a Story?

Yeah, it's too broad, innit! Specifically, then - how can I wrap a plot around something that is plotless? Or insert characters into something that has no such beasts? Hmm.

I suppose what my question comes down to is this: 'what is the difference between 'technical writing' and 'creative writing' and how can I close that gap, in terms of converting one to the other'?

(Posts question and then nips over to Warhammer to see how they do it there.)

  • Is the Tutorials section of the TikZ/PGF manual of the type you thought of? – celtschk May 31 '18 at 17:53
  • Hahaha yes, @celtschk, they are hilarious! :) "Euclid is currently quite busy writing his new book series, whose working title is "Elements" [...]. Up to know, he wrote down his text and graphics on papyrus, but his publisher suddenly insists that he must submit in electronic form. Euclid tries to argue with the publisher that electronics will only be discovered thousands of years later, but the publisher informs him that the use of papyrus is no longer cutting edge technology and Euclid will just have to keep up with modern tools." This comment will probably get deleted, but - thanks. :) – robertcday Jun 1 '18 at 8:19
7

As noted in this answer, 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.

  • 2
    Glad you answered, @Monica - I wrote this question with this comment on your profile in mind: 'I'd love to see more technical-writing questions here on Writing!' Helpful answer - thank you. :) – robertcday May 30 '18 at 14:15
  • A nice example of a board game that uses exacly the side box technique that you mention is the rulebook for Dungeon Lords – user23425 May 30 '18 at 19:58
3

You are referencing rule books for RPGs, so I am going to base my answer on those as examples, because I know the fascination of reading those books without playing the corresponding games.

There are a few reasons that make rulebooks interesting for me:

  • Artwork
    A lot of rulebooks for RPGs have very cool artwork that is distracting from the rules. After reading a handful of dry pages about what I can and can't do it's nice to look at what others imagine when they are playing such a game.
  • Examples
    Many rulebooks come with example scenarios that are supposed to highlight how the game is supposed to be played. A simple guide to character creation, how to resolve a certain action or how different mechanics play together. These examples provide a better way of understanding the rules and how they are supposed to be used. Rules are on thing - their application is another one.
  • Structure
    Rulebooks have a common structure, such as: What is an RPG? What roles are there for players/GMs? What is the main mechanic? How does character creation work? How do specific mechanics work? What abilities, such as spells, are there? The common structure makes it very easy to find your way around a rulebook. If you've read a couple you could find your way around a good book without a table of contents. This way I can skip right to the interesting part.

You could apply this in certain variations to user-guides. Simply replace "Artwork" with "Diagram". Make sure that it fits the current topic and is not just senselessly distracting. The examples shouldn't be in the narrative form you see in rulebooks, but you can use screenshots to show how someone should navigate software. The structure should be the same as other documents where you are working to make it easier to find the relevant parts once you get used to it.

The main problem is that too much creativity distracts from the core component: people want information. And they want that information now, because every minute lost could cost a little fortune.

People who are reading rulebooks are rarely under that kind of pressure when reading the books. During a session you should rarely, or better yet never, look up something because it distracts from the main thing, the game. That's why you normally have all the time you need to read such a book.

You can apply certain things from creative writing to technical writing. But it has to make sense and fit the general style that people are expecting. Even if it's boring, you are not being paid to have fun creating user-guides - you are being paid to create user-guides that will help users get used to software or find important settings when they are under pressure. Clarity is more important in such circumstances than creativity.

You could introduce characters to use those characters in examples. Look at Alice, Bob, Eve and Mallory to see how to do this. Or if you are going in a X for Dummies direction you might want to look at things like The Manga Guide to Statistics. But these are more for a different target audience than your average user guide.

  • 1
    The Manga Guide to Statistics - perfect, @Secespitus. :) – robertcday May 30 '18 at 14:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.