How to Write Effective Mud Help
by Sheila Summers
Most resources dedicated to game development focus on code and game
style, with an occasional foray into building or administration. I've
never seen a useful and complete resource for creating help systems, but
I've seen a lot of complaints from reviewers, players and developers
Confused? Lost? Try a help file.
Natalia's article, Help Systems
Suck, in last month's issue is the first article I've seen that
offers concrete advice on how to improve your help system. I would like
to supplement her advice with some basic techniques used in technical
writing (which is exactly what help files are).
Help files on a mud should be very brief and to-the-point, so I will
follow that paradigm with four simple strategies for creating effective
Be consistent, concise, clear,
complete and accurate
Use visual signals effectively
Give ownership of help to one person
Avoid common mistakes
Be consistent. This should be your
most important goal when creating your help system. Unfortunately, most
mud help systems are extremely inconsistent. If every help topic on your
mud contains the same basic sections, your players will be able to
quickly scan for the information they need whether the writing is
strong or weak.
Unlike other writers, technical writers must put aside their egos and
write with the understanding that their readers will not hang on every
well-turned phrase. In fact, they must design their documents to
facilitate scanning, so consistency in writing and visual signals is
more important than perfect writing.
On my mud, every help file looks something like this:
help <topic> : displays help on the topic
Our help system contains over 1000 entries, so if you have
a question about a topic, try the help files. If more than one
entry matches the topic you enter, a list will be displayed.
Note: Every time you use the help
system, we log the topics
you try to access. We use this information to help improve
our help system.
help help : displays a list commands useful for obtaining help
help a : displays all help topics that begin with the letter a
Related help topics: Index
Visual signals. Think about how you
looked at the example above. You probably scanned the blue headings
first and immediately noticed the bright red "Note" section. Then you
went back and read the actual text, and you probably didn't read every
Consistent formatting with clearly distinguished headers and titles
allows the reader to immediately see how the help is organized. The
following visual signals are present in my example:
Headings and subheadings are organized in a familiar pattern in all
The consistent color of the section headings makes it easy to scan
The Note section (which can also be a Warning) stands out because
color isn't over used.
Indentation separates the headings from the text for people without
If you have an online help creation system, create a template that
contains all the sections (in the proper order) that you feel your
players will need. Include sections that won't appear in every help
file; they can be deleted as necessary. Read through your existing help
and think about where it is lacking to determine what types of sections
you will need. Write your code to automatically insert this template
into new help topics when they are created.
Most people get frustrated when they try to write instructions,
because they don't know how to organize the information. If the section
headings are inserted when the writer begins to create the help topic,
half the writing is done and he or she can focus on well-written content
rather than formatting decisions. This leads to faster help topic
creation and more complete help systems.
Ownership of help. Most people who
build on muds are good writers, and writers like to have a feeling of
ownership of their work. However, most creative writers do not make good
technical writers because they are more concerned with creating
something that sounds good than with writing clear instructions.
Ideally, you should recruit someone for the express purpose of
maintaining your help system. Look for a journalist, if you can, or
someone with strong grammar and writing skills who prefers a
straightforward style. Once you feel confident in your help writer's
abilities, give him or her complete authority to change any help topic
written by another staff member.
Whether or not you assign help writing to one staff member, you
should have a help topic on writing help. It should contain the standard
section header layout, indentation guidelines, syntax conventions, and
anything else you can think of. The more you decide now, the more
consistent and usable your help system will be.
These mistakes should be diligently hunted and eradicated.
Overuse of color. Too much color makes your help files
difficult to read because the reader doesn't know what's important. I
recommend choosing three colors (and ONLY three) to use in your help
files: a header color, a "warning" color and bold for in-text emphasis.
Your players will quickly learn that headers are in bold blue, warnings
are in bold red and in-text emphasis is in bold normal.
HEADINGS IN CAPS. Most people are inclined to make section
headers stand out even more by putting them in caps. This only leads to
blocks of text that are difficult to read, especially on a computer
screen. Your eye does not discern individual characters of familiar
words. Instead, it looks at the shape of the word. Therefore, headings
in all caps must be read letter by letter, making reading slow and
Similarly, Most People Were Taught in Grade School to Capitalize
Nearly Every Word of a Title. Journalists call that "up style", and
most don't use it in headlines or headers anymore because it is
difficult to read. Use "down style" in your online help: only capitalize
the first word and proper nouns, and the titles of books or other
complete works if they are cited.
Lengthy explanations. You cannot keep a reader's attention
very long online, especially not in a fast-paced environment like a mud.
If you feel compelled to write long help files, consider putting that
energy and information into a players guide on the Web.
Long paragraphs. Lengthy paragraphs are difficult to read
online, because you get lost when you try to scroll or page down. Put
the most important details first and use two to three sentence
Incomplete help. Document every command on your mud with a
help file, even those that seem too obvious to be worth your time. If
you make changes from stock code (or create something completely
different from typical muds), include help topics or keywords for old
commands, topics, etc.
Help written for the wrong audience. The people who read help
files on a mud are typically not experienced, regular players. Think
back to your newbie days when you write help, and write it so someone
who has never logged on to a mud can understand.
Create a good, usable help system and I guarantee that you will keep
more players on your mud, existing players won't be annoyed by constant
questions on public channels, and your mud will have a more polished,
professional appearance. If you measure your success by the number of
players you have, a good help system can be a large factor in developing
a successful game.
If you get nothing else from this article, remember these five words.
Include them at the top of your help on writing help (you do have that,
Be consistent, concise, clear, complete and accurate.
November 2000 Imaginary Realities, the magazine of your mind.
© Copyright Information