[MUD-Dev] Importance of User Documentation

[rayzam]

----- Original Message -----
From: "Jon Morrow" <Jon at Morrow.net>
To: <MUD-DEV at kanga.nu>
Sent: Saturday, September 30, 2000 12:06 PM
Subject: [MUD-Dev] Importance of User Documentation
<SNIP>

> 1) Has anyone encountered a MUD with a good documentation model?  What
makes
> it good?  How can it be improved?

    Warning! Long post ahead! [feel free to skip examples to cut down on
your reading ;)]

    As others have been pointing out, there seems to be a few categories of
documentation:

  1) Commands. Any command used or typed should have a help associated with
it to explain it. If an incorrect argument [or none] is given, it should
give a quick one-line Usage: <blah>.

  2) Background. This includes the world(s), information on the storyline,
the history, etc.

  3) Characters. This includes all the options a player has for his/her
character. Information on races, classes/guilds, stats [str, dex, con, int,
wis, etc, only if you give it!].

  4) Universe. This explains how the world works: the magic system, skill
system, combat, social systems, politics, anything the player can engage in.

  5) Character Effects. Arguably, these can also be placed under characters
and universe. As it is, this category should explain things like poison,
damage & healing, diseases, stun, age, etc. Anything that can affect the
character during the course of play.

  6) Abilities. Every skill, spell, ability should have a help file.

  7) Glossary. A listing of terms both game-specific, and more general, that
players may not have come across. Even things that may seem common
knowledge, may not be if you have international players.

  8) Rules. Rules for playing the game, conduct, harassment, privacy,
legalese, etc.


    Each of these categories may best be served by a different type of help
system.

    (1) commands should all have a standard format, however, that should be
different than the standard format for (6) skills/spells/abilities. Why? It
depends on how the game works. From my example [Retromud], commands are done
automatically, and don't cost any spell points, hit points, or endurance
points to use. However, spells have a lot in common, and require more
standard information in the helpfile.

    Examples:
    The 'score' command:
Help for :score.

Command:  score
The score command will show detailed information about your character, such
as hit/spell/endurance points, money, bank, stats, exp, age, spouse, and
much more.
See also: skills, spells, sc, eq, i, exp, show

    The 'triple death' spell:

help spell triple death

Help for spell:

Type: Attack spell
Damage Types:
     Physical: 33%
     Fire: 33%
     Asphyxiation: 33%
Maximum Damage: 990
Additional Effects: Yes
Casting time:   5 rounds             Spell cost: 250
Spell level: 20                           Spell category: fire
Affecting stats: wis
Offensive: Yes                          Location: Anywhere
Target: livingtarget              Range: room
Components: VS
Alignment:
 -=Spell Description=-
This spell inflicts the horrible sacrifice known as the triple death upon a
living humanoid, which includes being garroted, speared, and then burned.
This
gives the caster a better chance to cast his next spell as a result of such
a
sacrifice attempt, and it can only be used on powerful beings worthy of such
a
sacrifice.


    (2) Background: the background may best be served [as we do it] on the
web pages. This allows for graphics and easier hyperlinking.

Example:
A player is checking the Pantheon [in-game gods, not coding staff], and is
looking at Sikkar, it notes that Sikkar is the deity of Good, and has
followers that are Templars and Paladins. Templars and Paladins are guilds
in the game. It is easier to entice the player at that point to just click
on either of those, and check out that information on the web pages, because
they can just use <BACK> to get back to their place, than it is to get them
to type 'help templar' or 'help paladin' after finishing reading the
background on Sikkar.

Even with a good listing of related topics at the end of a help, the more
topics you have there, the less likely it is a player is going to slog
through them all. But well linked web pages have a way of sucking you in,
following things that interest you.


    (3) Characters. As this is the information a player needs to
choose/design a character, it should be available upon entering the game.
Along with being in the general help system, the first few 'rooms' are for
choosing a race, starting class [guild], gender, description. Each of these
rooms has prominently displayed special commands to access this information.
In essence it feels more like designing a character than a straight out help
system, but it is the same.

    (4) Universe. This one is tougher. Many players will just go ahead,
especially if they have previous experience. Then when the first thing
doesn't meet expectations, they call for bugs, or question on channels.
That's fine, as other players[or wizards] are quick to point out the help
file.  Why is my sneak skill at 15% when I trained it to 80%? 'help bulk' -
the player is wearing plate armor, and is encumbered, and therefore skills
that require light armor are reduced.
    But these help files don't really have a set format. Instead, they tend
to be larger encompassing documentation. The kind that would make for
chapters in a boxed game. And players will treat it the same. Don't read,
until something seems incongruous, or until the player really feels like
they're going to invest time into the game.

    One side trick we use is to have 'A voice whispers 'Want to know how
spells work? Type 'help spellcasting'.' in the character creation rooms. So
any of these systems is whispered over time in those rooms. The longer
someone spends there, the more of these they are subject to. And of course,
the less familiar they are with the game, the longer they'll be there. It
may help a bit.


    (5) Character Effects: Again, this is a catch-all. As such, there is no
set format for these. Often these are referenced by a variety of the
Characters and Universe helps, and in return reference those.

    (6) Abilities - explained previously with (1) Commands.

    (7) Glossary - standard glossary format.

    Example: help constitution
Constitution (abbr. Con)-- This determines how physically sturdy and
healthy your character is.  It affects your hit point total.
HIGH CON = Never gets sick, rarely gets tired.
Example:  A bear.
LOW CON = Always getting sick, has a lot of allergies.
Example:  A butterfly.
NEGATIVE CON EFFECT: Beings with negative Constitution will find their
bodies give out and die.

    (8) Rules - Rules are legal help files that we require reading before
you enter the game for the first time. After you create a character, in the
character creation rooms, but before you enter the game, you are moved to a
rules reading room. It lists the rules you need to read about [harassment,
privacy, etc]. You can leave once you read all the requisite files, or enter
a command to 'skip' reading them, but acknowledges that you will abide by
them. Even if you skip reading them, you get reminded to read them when you
enter the game next, and they start off in your notebook [where you can
delete them].


    Overall:
    All of these should be accessible in game, with the help command, with
the possible exception of not being able to put all the various Background
in-game. But as much as possible of even that, should be in-game accessible.
    All help files should reference any others that are related, and by a
common format:
Help for: spellcasting.

Spellcasting has takes various forms depending upon the
caster.  Spellcasting utilizes spell points (SPs).
A spell's effect can be just about anything.

Spellcasting is affected by bulk (HELP BULK).
<Rest of help snipped>

    All help files should be accessible on the web page. Take the time to
make the cgi's or daemons to get your help files accessible from your web
site. It will be used. Many players prefer it, because it doesn't spam their
screen, and as a bonus, you get the best partial-match system available, the
player themselves.


    Rayzam
    www.retromud.org





_______________________________________________
MUD-Dev mailing list
MUD-Dev at kanga.nu
https://www.kanga.nu/lists/listinfo/mud-dev