Frag that Knight
Letters to the editor
- Jenna, Shattered World
A Revisitation of Help
- Robert Boileau
I Want to Forge Swords
- Sie Ming
- Luis Branco
Mud Excellence Awards
- Andy Awards
Mudding with Language Barriers
- Ntanel StormBlade
Cartoon - The Mud Simmer
- Rebecca Handcock
Enter your email to be informed when this site is updated.
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.
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
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:
look (at/in) [object or person]
The words in parentheticals are not required, while the ones in brackets
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
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
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
look (at/in) [object or person]
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:
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
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
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.
August 2001 Imaginary Realities, the magazine of your mind.
© Copyright Information