Member Discussions

Ok, I consider this an advanced topic because i'm not asking for the code, just your thoughts and ideas.

I'm implementing a helpfile system, based on key words.
I need it to be easy to use so the users don't give up looking for help.

So, several things:
* Should the files be retained in memory or loaded when needed.
* Key words. If words don't match exactly, should i use Soundex, Levhenstein, double metaphone, or all of the above to find similar help files?
* What methods are good for indexing, to minimize the system impact when searching?


My current thoughts are to load each file entirely into memory, because the top of the file would contain the keywords (or something similar), and the rest would be dumped into memory (string buffer). Multiple keywords would mean search-engine style finds. Highest number of matchs (with or without soundex?) specifies the helpfile(s) returned. I have soundex implemented, but i'm considering Levh. for spelling mishaps.

Ok, enough of that. Input time.

P.S. If you got this far, thanks for your time.

> * Should the files be retained in memory or loaded when needed.

There is no reason to retain them. Load them when needed and discard afterwards. Try to keep your data as disconnected as possible.

I never liked that soundex stuff. It's sometimes useful but not worth the false positives.

Why do helpfiles even need to exclusively use specific keywords? Why can't we just do a full-text substring search of the helpfile message, then display results from that? A 'specific match' keyword would certainly be useful, but I often don't remember the exact keyword the administrators created without navigating some unwieldy help tree. I'd take a page from Google, the King of Search, and get rid of 'em as primary mode of searching.

I suppose it is possible to do away with keywords if help files have a standard format that includes such information [after all, there are many cases in Diku-derives where the text of a help file doesn't include any of the keywords]. Necessarily, there would be an alias-type section of the help file that listed other important keywords and that, ultimately, reverses having removed the keyword section. The only true difference between systems is that in this method the text is also searched for word matches [slower, though potentially more information for the user...which has advantages (will find help file) and disadvantages (will get lots of useless matches)].

Personally, I liked the system I wrote on my last mud that basically searched for a prefix match of every keyword (now I wonder if substring would be better) and returned a list of help file numbers left of their titles for the inquirer. Then the person could type help #### to get each help file [for exact matches of which there was no other match, the help file was automatically displayed instead of the list of one item]. This gave the players the ability to get quick information about all help files pertaining to their query without being spammed with unwanted help file text.

As to whether to retain the files in memory or load as needed, that depends on whether one is using a database backend such as MySQL or SQLite or they are using a flatfile system such as that commonly employed in Diku-derivatives. If the help files are stored in flatfile-format then I think it'd be necessary to load the files into memory simply for the sake of portability [although I'm sure there are OS-specific search functions to locate matching help files, I don't honestly know of them]. If using a database backend however, then it is trivial to search and load them into memory only when needed.

Kelson

At TCP, we created our helpfiles in a heirarchal handbook-style format.

1.1 Roleplaying
1.1.1 What is IC?
1.1.2 What is OOC?
1.2 Combat
...
You get the idea (of course these aren't taken from our helpfiles). Keywords propagate up the heirarchy for optimizing searches and for relating topics. Listed helpfiles that match keywords show the heirarchy, allowing you to pinpoint the path of topics and possibly find related subjects quite easily. There isn't anything complicated about it, but it does require a bit more work when drawing up your help files. I suppose this comes from my background with Defense work - comprehensive manuals via sections. Even if you don't know the keyword, it allows you to find what you're looking for quite quickly - without doing a time-consuming algorithmic search - although I do provide one at a cost in pulses (it takes several pulses for searches).

(Comment added by lindahlb on Tue Aug 31 22:55:51 2004)

Oh, as far as in-memory versus loading. At TCP, we keep all the keywords in memory as well as the titles and a access count. The help files with the highest acecss counts are kept in-memory (~64k), and we also maintain a small LRU cache (64k) - which allows us to easily move them in and out of the permanent cache without doing fancy access count searches.

I'd say 'help backstab' etc, are pretty obvious searches. Perhaps you should look into some research regarding computer programs designed for individuals with an IQ below 80 (generally suffering from the down syndrome) which seems to be the latest fashion when it comes to desperate measures to attract newbies on muds.

My own mud uses a menu structure, where players get something like this presented:

  (A) Summary of Commands   (E) Race/Class Info      (I) Combat
  (B) Instructions          (F) Communication        (J) Information Commands
  (C) Game Areas            (G) Castles              (K) Objects
  (D) Interface Info        (H) Policies & Systems   (L) Movement

Players simply enter a, b, c, etc, to go to the corresponding help file, using '-' to return to the previous help file. It's still too much of a concept to grasp for most newbies though.

Menu driven systems, by nature, tend to work well for less proficient users of the system. They present all options, but require the user to proceed through all the steps. Versus the typical command line approach in MUDs that gives more power to the experienced user [one command to proceed to the destination vs navigating the menu structure], but is harder to learn for the newbie.

People tend to have trouble adjusting to systems different from what they're used to. If presented with a menu system in games for which they're routinely presented with a command-line approach, then they may not be sure what to do or may be annoyed at the slower access to data. The help file may indeed ensure that users always get to the data needed, but it won't be in one step as users are typically used to in MUDs. The same can be said of GUI's though :) My approach takes the (IMO) best of this system [presenting available options] and removes the menu-driven system [see posting above].

Kelson

My system sucks, in that an index is not built, though I would if I could. Basically, I prepend '*.hlp' to the argument, then search the help directory for a file named that. If found, it loads the file, displays it, then free's the memory. For larger help files, a temporary buffer attached to the socket is used to hold the unread text (paging system used). This is nice because I can add new help files without resorting to large memoryu free's and re-allocation while the game is running. What I need to figure out is how to get a file listing of the help folder in order to create an index. I'm thinking I may have to resort to a perl script since I can't figure out how to do it in C ( in perl it would be like 'foreach (@files) { print OUT '$_\n'; }').
I don't want to hijack this thread but if anyone out there knows how to do that in C, let me know :-)

All your help files are named by the applicably keyword(s)?

Searching the directory is a slow way to find a match [disk access is orders of magnitude slower than memory access]. As far as making an index, just read in every *.hlp and store in some container then print out the container [vector,list,deque,set,etc].

Kelson

Menu driven systems, by nature, tend to work well for experienced users. They present all options, easily reachable in 1 or 2 steps that are as easy to remember as the location of the key hole. This versus the typical command line approach which forces the user to remember 1000 keywords, or enter search queries that oftenly produce too many, or non relevant results.

Dogs tend to have trouble adjusting to systems different from what they're used to...

Oh well, you've obviously never played a mud using help menus. It's hard to speak of the [best] system if you do not know better.

Any system works well for an experienced user. That wasn't my comment. I said that they don't work as well as a command-line approach would for a user of equivalent experience. It takes longer to navigate to the needed answer via a menu system than by command line.

By nature of their use, keywords shouldn't have to be remembered. When a user thinks of some information he/she wants, they should simply enter some tidbit of information pertaining to that information and a proper keyword match should locate it. The issue of returning too much data or irrelevant data is a different matter. Too much returned data can be just as applicable to the menu system as the keyword system and, in the end, is best handled by more a good information display system [for example, in my system we list off the titles to cut down the spam for the user instead of citing the entire help file...best we can do so far, although maybe displaying a relevant portion of the help file in addition to the title it would be improved] and more specific queries or advanced search options. The non-relevant results are directly related to the differing opinions of the original maker of the help file and the eventual recipient. There really is no way to correct that problem.

>Oh well, you've obviously never played a mud using help menus. It's hard to speak of the [best] system if you do not know better.

I hate when people assume that, just because someone denounces their rarely utilized method, other people have not used their system. When I first started changing up the help and social files [softcoded socials] I did it via a menu-driven system. This was fine in the beginning, but it became a pain to create the menu system and add help files in all applicable spots of the menu's tree system. Additionally, it was a pain to guess as to which option would have the needed data...a wrong choice could lead a couple levels deep just to realize one was progressing along the wrong path. In addition, the attribution method of listing help files requires that users possess at least a rudimentary knowledge of the topic of the help file. For example, I see a skill in practices named 'Cherop'. Granted, one could blame poor design in forming a name the player can't associate with anything, but the system you praise has no built in system for dealing with this issue of knowing only a name and nothing else [although, I do actually know it is a skill...what type of skill?]. Because of these drawbacks, I changed to my current system and haven't heard any complaints yet.

Now that I've said that, there is nothing wrong with menu driven systems. In fact, I like using them for OLC editors even though I might think the command line approach is better for the experienced user [maybe I'll have a toggle builders can use].

Kelson

You guys have some interesting ideas.. i like the menu system idea, considering my helpfiles are probably gonna be centered about categorical subjects, it'd be fairly simple to make a system like that on my server.

Currently, I run through the directory, and read in the file. I then search the file for the keywords (with optional support for several phonetic or spelling helpers err.. Soundex, Levenstein, and double metaphone). then I free the buffer.

I don't see why i can't implement a menu instead, and use search-techniques in case they can't find the topic by navigating the menu.


BTW: for a file drill in c: google "opendir"

>In fact, I like using them for OLC editors even though I might think the command line approach is better for the experienced user [maybe I'll have a toggle builders can use].

The first olc implementations were command based, most experienced builders will disagree with you regarding the command line approach being better or faster. I personally hated the command line version.

>Granted, one could blame poor design in forming a name the player can't associate with anything, but the system you praise has no built in system for dealing with this issue of knowing only a name and nothing else

The help file system still works with keywords, as you can see you assume too much with little information or experience. An entirely menu driven help system would be crazy.

Menus don't have to cover all help files, only those where a menu would be the logical choice, and those oftenly are the ones where a user would end up searching. And ofcourse help files that can be reached with a menu can still be accessed with a key word.

But as I said before, menus are faster than searches on average because they are more reliable and the menu path can be partially memorized if used frequently enough.

Anyways, menus are optional, just like search routines. Not sure why you're making an issue out of it.

>The first olc implementations were command based, most experienced builders will disagree with you regarding the command line approach being better or faster.

Menu-driven systems can't be faster than command-line systems. It is in their nature. In any system for which there is more than one menu, there will be at minimum one intermediate command necessary simply to execute a command. Command-line systems do not have this restriction and therefore will always be faster in the abstract. I'm not claiming command-line are abstractly better, no system is better in and of itself than another system. It depends on the requirements. By the way, a command-line system has no restriction that forces it not to display the information about whatever the character was last editing. As far as I was aware, this was the only reason to choose a menu-driven system over a command-line, but could you please point out others?

>An entirely menu driven help system would be crazy.

If you had just said, that beginning, that you're using both a menu-driven system for navigating help files and a command-line system for searching for particular help files then we wouldn't be having this discussion. I think your quote speaks well enough for a menu-driven help system though.

The rest of your post essentially states that the menus aren't required and you're using the best of both systems. I have no complaints with advising someone on using such a pair of systems, merely that it seemed implied, at least to me, in your posts that you were using ONLY the menu system and advising to utilize it to the exclusion of the command-line approach...

>My own mud uses a menu structure, where players get something like this presented: [two levels up]

Not sure why I thought that.

>But as I said before, menus are faster than searches on average because they are more reliable and the menu path can be partially memorized if used frequently enough.

While they may be more efficient, I would argue that they are neither more reliable nor faster. The computer can easily search through tens of thousands of 3 keyword [on average] helpfiles a second which, tends to make them much faster at such a repetitive and simplistic task than humans. We might notice such differences as a typo, a prefix, or in general a very close match, but the computer can be programmed to identify situations where this might be the case. As far as reliable, both systems are only as good as the intuitive-ness of their keyword or menu placement to the current user. However, whereas a keyword search through every single help fill will definately tell you that there is no help file with that keyword [or none that help you], one would have to fully map the help file menu tree to be assured of this fact. As I said before, if I know nothing about some strange skill on my practice list then it would take me much longer to find it in a menu system than to locate a keyword match in the help files [assuming, naturally, that it is correctly placed and keyworded in each systems].

Partially memorizing the path [or even fully memorizing it] still won't make the human locate the file faster than a computer-based search. The strong point of a menu system is not that it is faster in any way, shape, or form than a command-line approach but rather that it is able to process input according to the current state of the system [one could argue that MUDs are their own form of menu systems anyhow, but that is neither here nor there] and present all options to the user. For example, using an OLC menu system that shows all keywords to the user lets them see what commands are valid and applicable at that level whereas that wouldn't be possible with a command-line system for which all commands are valid, but not necessarily applicable.

Personally, I always liked help files users could check on to see major subsets of other help files. It is similar to a menu system without the necessary coding.

Kelson

Our system uses a mySQL backend, and the results are queried never loaded into memory just displayed.

If you wish to see an example or would like to try it out, drop me an email jcrenshaw@c2-solutions.net

I offer my sql header and basic functions for use in a MUD for you to use, as well as an example of how I request and display a help file to a user.

Intermediate knowledge of C and some SQL API is required.

Regards,

JCrenshaw

We on DuneMUD use table of contents based help. In the future I expect to expand it so a user will be able to search by a string in the file. For example, 'search help guilds' will return all the files that have 'guilds' string in them.

This is the layout of the help, after you type 'help' command:

      To read about a specific topic, type 'help [topic]'        

General
DUNE            gholas          guildinfo       guilds          healing         
killing         marriage        newbiehelper    newbiehelpers   politics        
quests          reimbursement   space           stats           

Communication
allies          boards          communication   converse        earmuffs        
emote           htell           intermud        lock            mail            
pose            reply           say             shout           tell            

Combat
aim             briefme         briefmon        combat          defense         
kill            party           powerdown       powerup         types           
unbriefme       unbriefmon      unwield         verybriefme     wear            
wield           wimpy           

Information
brief           compare         coverage        dictionary      examine         
ii              info            leaders         levels          pkills          
pkrank          plan            qwho            rank            report          
score           skills          uptime          who            

I wrote a helpfile system on my last game, that was memory resident and fairly robust. On my current project, I wrote a similar system (described below) that is stored in MySQL. While not many helps exist in what I'm working on now (less than 50), we previously had over 1000 helpfiles that were easily found, easily maintained, and relatively quickly returned to the user. Soundex matching was accessed if no return was found on the original query, and compared only against main names, not keywords.

Two fields were used for finding the helpfile based on keyword. The first was a match against the 'name' field; that is, the stored value of the helpfile itself. Multiple helps could have the same name, and if so either the first one found was returned, or if one in the list was flagged as key (boolean), that was the one returned. Thus, key helps had higher weight than others, in terms of display value (true for all methods of output).

If no match was found on name (or partial name, with full match assuming higher weight than partial), a second iteration was done for keyword substring matches. This allowed a 'look' helpfile to be found with 'examine', 'see' or other keywords.

Failing a positive find against both name and keywords, the soundex routine looked for close matches of the name value, and suggested anything found as a possible match.

With 1000+ helpfiles, the time to traverse the above was negligible. This will rise with the SQL query concept I have now, and eventually will need to do something like Brian has done, and keep a portion of the most read in memory. I also have a weight value system where a user can weigh a helpfile's utility, and the higher values show in searches before lower value ones. This has relatively little testing done on it right now because of our development state, but I think it will prove useful.

The helps are indexed into categories relative to the game paradigm. On the previous game, this broke down to areas such as communication, magic, combat, information, policy, etc. It was possible to explicitly limit a helpfile query to an index, such as 'help information look' or 'help policy look'.

One could also receive a listing of helpfiles within a specific index, by 'help [indexname]', such as 'help communication'. This could also be toggled to show a brief description of each helpfile within that index, by 'help index [indexname]. This may return:

---

              Helps within Communication
Emote
  Command to create a third-person description of an act your character is performing.
Mail
  Explains the usage of the in-game mailing system.
OOC
  Explains the usage of the Out Of Character communication channel.
Say
  Primary method of communicating in-character with other players.

---

and so on, for each help within that subcategory. This allows a quick at-a-glance understanding of the output helpfiles, and allows the user to drill down further if necessary (help mail, or help communication mail).

One could also do a search of the body text of a helpfile, and either receive match-name output ('The following matched your help search') or match-name-brief output (showing the list as above, with brief information about each).

The helpfile structure included the name, keywords, brief, syntax, body, times read, last modified, seealso, and unique-number fields. Unique number allowed one to traverse the helpfiles with 'next', 'previous' and 'random' commands.

The combination of commands available allowed the standard concept most Diku-esque Mudders were used to to work, wherein they simply type 'help whatever' and are shown a return of output. Additionally, it permitted those who became familiar with the breadth of the system to take advantage of it, and to use it to quickly find the helps that were necessary for them. We also had an 'assist' command that allowed one user to find a particular helpfile and then assist it to another person, who would be able to reference it without having to go through the trouble of searching for it himself.

---

Regardless of the method taken to implement a help system, the choice made, and the time put into it, is nothing if the helps are not maintained. Intrinsic with any good help system is the responsibility of the author(s) to keep the helpfiles up to date, relatively typo free, and related to the topic of the help. If this is not done to some degree, even the most intuitive, advanced help system will fall be the wayside of unused projects.

I do it by keywords, and use an index system that will search the prefix of keywords...

You can get all helpfiles starting with a by typing 'index a'

And outputs like this....

ALLOW - Immortal command.
AXE - Explains the different weapon types available to you.
AFFECTS - Explains what the affects command does and how to use it.
AREBOOT - Builder command.
ASAVE - Information on saving your work.
AEDIT - Builder command.
AUCTION - Help with auction commands.
AFFECTS TABLES - Builder resource.
AC TABLES - Builder resource.
AUTOSET - Builder command.
AUTORESET - Builder command.
AFK - The Away from keyboard setting.
ADVERB - Commands for socialising.
AREAS - Useful commands.
ADVANCE - Immortal command.
AT - Immortal command.
ARMOR - Spell: available at level 2

Each helpfile has a "comment" line that briefly describes the file so you can browse the indexes and then find what you need. Worst case scenario, do index a, index b, index c, you'll find it eventually :p