The MUD Development forum.
Game Development Discussion, Chat, Technical Debate, and people who just love games talking about building worlds.

Home » Hosted Mud Projects » Wheelmud » General » New, Feature Full Help System - WheelMUD - A C# MUD Server - Forums - WheelMUD - Design
New, Feature Full Help System - WheelMUD - A C# MUD Server - Forums - WheelMUD - Design [message #339] Sat, 21 March 2015 22:41 Go to next message
Karak is currently offline  Karak
Messages: 489
Registered: March 2015
Location: Seattle, WA
Senior Member
Wheelmud
This thread originates from prior WheelMUD forum software archives. It has been migrated here to preserve the contents.

Post by Pure (27 Sep 2010 11:56 AM):
Hi guys!
I have been working on a new help system for WheelMud, as opposed to the current just showing the command description and usage information.
Currently, I have rewritten HelpManager.cs, IHelpManager.cs, HelpTopic.cs, IHelpTopic.cs and Help.cs for 0.4.0.0, I will update with the code once I have finished it for the current revision.
Basically, the system reads help not from the database, but from the filesystem. The Files\help directory to be exact. These are loaded into memory during HelpManager.Start(Wink and can be called using the help command, an argumentless command giving the index page.
An example help topic:
Quote:

0|index|example
This is an example help topic.
This is a <see cref="test">link</see> to another topic.
The first line is a list of aliases separated by '|'.
The name of the file is irrelevant, unless it is 'Files\help\index.help'.
This file will be used for the index, which will be stored in a variable on the HelpManager, as well as in this List<helptopic>.</helptopic>
Hope you like!

And that is basically how they work. They are MXP enabled, so &lt;, &gt; and &amp; should be replaced in the right way.
I would like to start up a standard collection of help topics that are shipped with WheelMud. And, for that, I need your help! If there is any collaborative text editor availible anywhere, I would like to use that to keep track of the current topics.
What do you think? I hope that this system will replace the current way of getting help. Please post your thoughts, queries and issues.
Thanks in advance!

Post by Fastalanasa (27 Sep 2010 01:27 PM):
Yes! The current stuff looks pretty lame. Razz
Just one minor tweak to the breadcrumb. Have the 0 be "root" instead. Everything else looks peachy. Full Speed Ahead!

The Wiki is perfect for collaborative stuff. I'm going to give you rights to write to it, although you should already have them. I'll create a new topic called "Help System" and we can move specific documents there.

Post by Karak (28 Sep 2010 12:25 AM):
Cool. I've got a couple thoughts. Please view this as constructive feedback and open discussion rather than any sort of mandate or whatnot. Smile Our help system is certainly not where it needs to be yet and this does look like welcome progress.
I don't know what you mean by collaborative text editor... Text usually takes pretty well to source control, especially if line returns are used in the content. So people can collaborate on that the same way they collaborate on code. If you mean simultaneous editing of the same text file, seems overkill? If you're just talking about going back and updating a list of topics that are being worked on/completed/etc, we have a couple built-in options: we have a wiki area that would serve this well, or use the 'edit' feature on a forum topic to keep a list up to date. I periodically update a pinned <a href="aft/479/Default.html">list of Commands</a> topic that way.
More to the meat of the subject, you'll probably want to read up on <a href="aft/541/Default.html#603">the Actions Accessing Actions topic</a> which discussed various aspects of help system, if you haven't yet.
On what sounds like inventing new file formats and doing custom file load parsing, IMO that can be overkill and perhaps detrimental. Let's say you have a class called HelpTopic. If you mark up the properties of that class properly, XML serialization/deserialization is done automatically for you, and then you have a data format that is familiar, supported by existing tools/viewers, and somewhat self-documenting to boot rather than "memorize that the Xth line describes the Foo". The help file loader becomes "try to deserialize each XML in the Help directory." If someone broke the schema, most likely it'll result in an appropriate XML read error that could be caught by the deserialize and displayed in the MUD harness output area, rather than potentially silently putting the wrong data into the wrong property since the file format wasn't quite understood. A schema could even be employed to validate the help files outside of rebooting the game.
As far as some of the attributes in the command classes themselves, particularly those with short texts like the brief description that would appear in the "commands command," I do prefer them to be there. TBH I think even the command help text itself may make sense to be there at least sometimes, as it keeps the content close to the code in a case where the two really are strongly tied together; when a developer adds a new syntax to the Foo command, they'll generally forget to update the Foo help text (or opt not to bother due to true or feigned ignorance of the help file), unless it's right there in their face too. Command enhancement and related help text updates should generally be performed hand in hand. This helps foster sharing too IMO: say I invent a "RoShamBo" command and want to share it with other WheelMUD instances - ideally I should be able to post the contents of RoShamBo.cs to share it if that's the way I want to share it, rather than telling people "make this file with this contents then another file over in the help file system with these contents."
IMO the best thing may be to support both paradigms and let the MUD admins use the policies they choose on documentation storage. Imagine you had the ability to have a command whose static init contributed to the help system, called something like:
HelpSystem.Instance.UpdateHelpTopic(new HelpTopic(Wink
{
Aliases = new string[] { "RoShamBo", "rock", "paper", "scissors" },
Content = "When you use the RoShamBo command, yada yada yada...",
}
It would be pretty easy to include that in a single RoShamBo.cs, and those admins who have a policy to keep all documentation only in the help files folder would rip it out into a new help file, after they've tested, decide they like, and adopt the code.

Post by Pure (28 Sep 2010 04:30 AM):
Yeah, keep the old system, but only use it if the article cannot be found.
I think that serialization might not work well for the system; as I want the pages to be able to include MXP and such. I think I will stick with the current text files.
I have edited the wiki with details on how to add a help topic to it. I have only made a very simple index page, I'm no artist!
Please could some people help by adding some more?
Thanks in advance!
Re: New, Feature Full Help System - WheelMUD - A C# MUD Server - Forums - WheelMUD - Design [message #493 is a reply to message #339] Tue, 24 March 2015 23:52 Go to previous messageGo to next message
Karak is currently offline  Karak
Messages: 489
Registered: March 2015
Location: Seattle, WA
Senior Member
Wheelmud
Some goals for the help system:
1) Discovery of commands and usage
2) Non-reboot updates
3) Devs need to update it as feature changes/improves
4) Pagination

Some thoughts on those:
1) The "commands" command or "help" command should find all Currently-available commands, including context-sensitive commands.
2) One strategy is to have online editing of these. One solvable wrinkle there is context-sensitive commands. Another strategy is the attributes. This also will support non-reboot updates via the new attributes values coming in via the MEF Recompose mechanism.
3) IMO the only sure-fire place for devs to notice, and consequently be likely to keep updated, the "help" contents for a command... is as close as possible to the code itself. It doesn't get any closer than attributes or properties on/in that code. So IMO we might want to keep attributes as the standard for now, and as we get closer to the v1.0 polish stages, we know our commands are well-established and can think about crafting good help files and maintaining other data sources for those help contents.
4) Pagination (at least a 'more' command) gets solved at a session output level, rather than feature level. I feel like we had a discussion about how we could handle paging up and down including percentage read, of a given blob of output (IE reusable for help files, bulletin board notes, etc) but I'm not finding that now.

[Updated on: Tue, 24 March 2015 23:52]

Report message to a moderator

Re: New, Feature Full Help System - WheelMUD - A C# MUD Server - Forums - WheelMUD - Design [message #494 is a reply to message #339] Sat, 28 March 2015 18:54 Go to previous messageGo to next message
Duane is currently offline  Duane
Messages: 4
Registered: March 2015
Junior Member
Administrator
Pagination needs to be supported by the server first.
Re: New, Feature Full Help System - WheelMUD - A C# MUD Server - Forums - WheelMUD - Design [message #495 is a reply to message #494] Sun, 05 April 2015 13:29 Go to previous message
Karak is currently offline  Karak
Messages: 489
Registered: March 2015
Location: Seattle, WA
Senior Member
Wheelmud
Yup, when I say at a "session output level" I do mean on the server. I was just pointing out it shouldn't actually be considered a sub-feature of a command like "help" nor should "help" even "know" about the system. Rather, I see pagination as a generic function of how many lines of output are being sent to the client between prompts, compared to their client-negotiated supported rows (or a user-defined override), or some reasonable default if unspecified and unconfigured. And alternately as something help would know about, if only to simply mark "this big blob of text is static-reading-content-like; apply any message-boardish output logic" which may or may not allow for paging back up, scrolling, and so on beyond a normal -more- prompt.
Previous Topic: mysterious registration - WheelMUD - A C# MUD Server - Forums - General - Lounge
Next Topic: Cannot DL the Data.RavenDb NuGet dependencies ATM - WheelMUD - A C# MUD Server - Forums - WheelMUD -
Goto Forum:
  


Current Time: Thu Nov 23 08:46:28 PST 2017