The copyright situation for this article is unclear. It does not belong to the author of this site. Please see the copyright notice. If you have information about the copyright contact me!

How to Write Effective Mud Help

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 about them.

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 help:

1. Be consistent, concise, clear, complete and accurate

2. Use visual signals effectively

3. Give ownership of help to one person

4. 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:

Syntax
  help <topic> : displays help on the topic

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

Examples
  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 word. Right?

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 help files.

• The consistent color of the section headings makes it easy to scan for information.

• 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 color capabilities.

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.

Common mistakes

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

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

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, don't you?):

Be consistent, concise, clear, complete and accurate.

November 2000 Imaginary Realities, the magazine of your mind.
© Copyright Information