Trouble Finding Help Topics

I feel like burying stuff in tutorials without explicitly linking to them where people instinctively go for information is problematic. As the tutorials grow and flesh out, it becomes harder and harder to find information you need.

I’ve had this problem a lot and miss things that are in documentation despite searching for 15+ minutes every single time I need to look something up despite having traveled around a lot. I then have to bug you and disrupt your dev time or others. :frowning:

In general, it’s very unconventional and inefficient for both devs and users to scour tutorials for documentation (even with google and browser page find). This leads to the tutorials that document functionality/commands to be more likely to be out of date and have inconsistencies between repeated documentation. Also, I think most users are trained to look at tutorials as how to use commands, not for command documentation/reference.

My suggestion is there are two prongs to the help system. A short/reference help for the main file like you have, and then any existing extended help documentation links auto-formatted at the bottom:

See also: or See advanced help:

I don’t really see this idea as a help “hub” like the old C servers have in their help files and you wouldn’t need to get at these from any other location.

Are you on the latest version? Because there already is a multi-level help system. For instance:

Chat Tutorial - gives an overview of the chat system for those who aren’t already familiar.

At the bottom of that are links to specific command references, like Channel Commands.

And within Channel Commands, there’s a link back to the tutorial, like

Get an overview of the chat channel system in the Chat Tutorial.

There’s also the quick reference command, where you can do qr channel just to see a quick list of all the command syntaxes.

There’s even a way to search the help files.

The help system has a lot of competing tensions. It has to work for folks who are brand new to MUSHing, veteran MU players new to Ares, and veteran Ares players. It also has to accommodate different permission levels (some games may lock down ‘manage wiki’ to admin, but others might have separate wiki admin), the plugin architecture, and the ability to override parts of the help with game-specific information.

What’s there may not be perfect, but I think it’s the best possible compromise. And I never mind questions if somebody can’t find the answer in the help :slight_smile:

1 Like

I am on v75.

Okay, now I see it. Since it id formatted as a relative wiki link, it makes it unfriendly to telnet client users. I can’t simply click it and it’s unlikely to catch players’ attention like the web rendered view does (I find telnet client players are unlikely to jump out to help unless they need to link someone else to it, like if someone can’t find some help, so I think this will be easily missed).

help chat takes me to channel help and that doesn’t have any link to the Chat Tutorial or Channel Commands. D:

Searching for help is very limited and problematic as it is implemented I’ve found:

A lot of times keywords I think would take me there do not. It doesn’t seem to actually search the body of help files (which I understand there might be good reasons for that right now in Ares’ stage of development).

Classic example is help pose takes me to information about posing, but then what I wanted was help order because the command is pose, that’s what I remember, and that’s how I want to look up documentation.

This is a pretty difficult case and may point toward simply changing a command name to make this easier, but there are other cases (I can’t think of off the top of my head right now) where there are no command conflicts like this.

Thoughts on these?

I think the qr command is more what you’re looking for (it’s an alias for help/quick). This is for people who already pretty much know what they’re looking for and just need the syntax.

For example, qr pose gets you all the pose commands at a glance, including pose/order. Same for qr channel for the channel commands.

This is something that many people transitioning from Penn/Tiny to Ares struggle with a little at first, but most folks get used to it pretty quick and find qr to be very handy.

The more detailed help/tutorial files are primarily intended for the newer players, and they’ll be more likely to be using the web-based help files that have clear cross-links, emphasized notes, etc. So that’s what it’s optimized for. You can also do a full-text search on the web portal.

The current system is certainly not perfect - I just noticed that ‘Posing’ was listed as a main tutorial and not linked under ‘Scenes Tutorial’ as it should have been. And no doubt there are keywords that could be added to certain articles. ETA: I can also highlight the relative links, to make them stand out more, and maybe mention other articles at the bottom.

Those sorts of requests I’m more than happy to entertain, but the overall structure/user experience had gone through many iterations at this point and I’m pretty happy where it’s landed.

Moved the discussion to its own thread since it was getting a bit more involved. (And I was having trouble following the thread of previous replies myself :slight_smile: )

Also here’s an example of what I added to the bottom of help topics:

help pose:
Posing
------
blah blah
------------------------------------------------------------------------------
Other topics in '4 - Writing the Story': 
scenes, pose_format, scenes_tutorial, pose_order, ooc, places
------------------------------------------------------------------------------