Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Rewriting User Guides as Stories

+0
−0

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.)

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/36510. It is licensed under CC BY-SA 3.0.

0 comment threads

2 answers

You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+0
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »