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!

A Revisitation of Help

by Robert Boileau

Help files, as indicated by Natalia in October's edition of Imaginary Realities, are often sparse or outdated, or simply nonexistent. All of her points are valid, from what I read, were valid, and often frustrated me when I was a player on other muds. When I began the MUD for which I work, I made a resolution to never have obsolete or missing help files.

Some nice chicken stock

The Primeval stock from which muds arise.

Oh, how naive I was.

In the past two and a half years, our code has changed tremendously from the stock it originated as to something which is very much unique. There is now a high learning curve to the game, and I blithely thought our help files were able to overcome that. When we introduced our new combat system, we also brought on a new Immortal to help the players understand the changes which it entailed. I charged her (Elbahna was the name, sadly no longer with us) to not only educate the players, but to point out to us - the programmers - what we could do to make a transition easier. After day one, she sat me down and explained using very small words that our help system just wasn't up to par with what was necessary.

After succumbing to her suggestions, I did a total revamp of the help system. I was loathe to lose our previous work (800+ help files), so had the challenge of making it not only meet her specific performance requirements, but to have it backwards compatible so we could modify, rather than rewrite, the existing helps. Had I done this rewrite when we began, it would have been so much easier. :P I won't say it's the best system out there, but it is the best I've seen (even accounting for the biased view I'd naturally have). I'll detail it here, in case others want to use the same approach. Forgive me if I use broad concepts; I prefer that people write their own solutions.

First, to prevent stagnancy, there's a 'last modified' field which is autoupdated whenever the help file is changed using our OLC editing approach. Along with this is a 'times read' value, to help us see trends in help requests. These are not modifiable within the editor, for no reason other than I wanted honest values returned here.

Each help file has a the following fields (detailed below): level, keywords, name, brief, class, syntax, text, index, imminfo, and seealso.

LEVEL: sets the minimum level at which a help file is viewable.

KEYWORDS: allows you to set the keywords which reference the help file (such as 'scabbard' to 'sheath', so they both pull up the same help file. This area recognizes partial name completion, and is quote-savvy, so "scab" would match, but if " 'scabbarding your sword' " were a keyword, "your" and "sword" would -not- match, since they are in the middle of a field requiring a prefix (so 'scabbarding you' would fit, or 'scabbarding your s').

NAME: is the name by which the help file is most easily referenced. (more on this below)

BRIEF: this field is used when the players ask for an index of a word or phrase (again, more on this below)

CLASS: we have several classes, to allow players to better understand the applicability of a help file. They range from command (something that's used with no prefix) to guildskill (only usable by a particular guild) to prerequisite required (so they understand they need another ability before this one can be used).

SYNTAX: a separate field from the text, so we can better format the text entries. All of our syntaxes are standardized, so they look the same in each help file. Basically this field is where you would explain how to use the command properly:

     Syntax: look
             look (at/in) [object or person]
             look [direction]

The words in parentheticals are not required, while the ones in brackets are.

TEXT: is the meat of the help file, the informative part of it. This is where you explain what the purpose of the help file is. It doesn't hurt to cite examples here, so the players gain a better understanding of what you mean. Again, I encourage standardization - we have all our help files in white text, with samples in bright cyan, and references (to other helps) in dark cyan.

INDEX: Sets the parent category of the help file. More on this below as well.

IMMINFO: this field is viewable by Immortals only, to better expound on a particular help file. Some examples would be an in-depth explanation of a spells affect, or answers to how a particular skill works, so the Immortals don't have to say "I don't know, ask a Programmer."

SEEALSO: Allows you to link to other help files. We chose to make this static, rather than a dynamic link, although you could certainly do either way.

KEY: A boolean field which marks the help file as a key help file. We iterate through the helps twice, the first time looking for a key match, and the second looking for any match if no key is found. This allows you to have two (or more) help files with the same keyword, and ensure a particular one shows first.

The NAME and INDEX field go hand in hand. When a player types 'help' without an argument, they are shown all the indexes of the helps. We have 26 of them, ranging from Commands to Skills. These are the broad categories into which a help falls, allowing a player to descend into a category and isolate the help they want. So when they have a question about moving, they can type 'help' and see there's a 'movement' category, then type 'help movement' for a listing of all the helps which fall under that index. They can then request one of the help files listed. If there's more than one help file, in more than one category, they can narrow it down by including the narrower: help movement [help name].

A player can view the BRIEF output of a help by typing HELP INDEX [keyword(s), index, or class]. This shows the name of the help file, which index it falls under, and the brief description of it. If the help doesn't have a brief description, it is not shown here.

So a player, typing 'help look' (or 'help information look') would see:

Help file for LOOK

Class: Command
Syntax: look
        look (at/in) [object or person]
        look [direction]

Look is used any time you wish to view something, be it the room (look without an argument), a book/board (look book, or look board), a specific item or person (look name), or a direction. It is versatile, and you may use "at" to specify an object or person if you wish.

You may specify a particular instance of something to look at also, such as "look 2.book" to look at the second book.

See also: GLANCE, PEEK

(Subject area: information Last modified: Sat Jul 7 07:11:28 2001)

This shows them the information they need for initiating the command, the acceptable arguments of the command, and sends them to other possible help files they may wish to view, in case it does not answer all their questions. They can see how long ago the help file was modified (most useful when a command has been changed, or seems to be operating differently, and the help file has not been updated in 2 years...). It also gives them the CLASS and subject (INDEX) area of the help. Were they to do a "help index look", they would see:

Look
  Information about how to use the look command.

Of course, if they indexed 'command' or 'information', they would see quite a bit more output than the single help file shown above.

I should point out that, after talking with KaVir when I began this rewrite, he suggested we add something called 'soundex matching', which does phonetic sorting. This way, even when a help file is misspelled, it may still find it. So a request for 'lukh' will still direct them to the proper help file:

     No help on that word.  Perhaps you were looking for the following:
         general Lag       information Look

If there is no help file found, and no phonetic match, the help file request is sent to all Immortals online, and logged in a file which I view daily. Helps which have been overlooked are written as soon as possible. Those which exist but do not have that keyword are updated to have it, so the next player who requests (for example) 'help view' will see the look help file.

To date, we have 862 help files, ranging from explanation of commands to FAQ's for each index area, to commonly known historical events. A player could, in theory, log into our MUD and, without using any help other than the system, create a character which knows the basic histories of the land, how to act in social circles, how to move and manipulate objects, etc - which most certainly could NOT have happened with the old help system.

I encourage others to do something with their helps. The stock help system with most code bases leaves a lot to be desired. If you've any suggestions of your own, I welcome the input.

Robert Boileua is a Programme on The Inquisition MUD.