I think this is partly on Evennia, not just the Arx staff. (Sorry, Griatch.)
Specifically, Evennia generates a lot of the documentation automatically for each command; in a lot of ways, this is great; you include the documentation in the command source code, and a helpfile is made for it. No worries about documentation being out-of-date; you edit the command, you edit the description RIGHT THERE. I wish more things supported this.
But conversely, if you alias a command to another command then 'help' for both commands will give you the same help text; this leads to the home/+home, time/@time versus guards/@guards/+guards situation you describe. And additionally, since the coder is writing the documentation right there in the command, you... well, are getting coder-written documentation. Which (as a coder) I must admit is not always the ideal; sometimes you want an editing pass by someone who doesn't think in terms of code. 
(That said, I object on general design principle to having command, +command, and @command do different things.)
a.k.a. Packetdancer (or "Pax" for short)
@Sparks said in Coming Soon: Arx, After the Reckoning:
I think this is partly on Evennia, not just the Arx staff. (Sorry, Griatch.)
Specifically, Evennia generates a lot of the documentation automatically for each command; in a lot of ways, this is great; you include the documentation in the command source code, and a helpfile is made for it. No worries about documentation being out-of-date; you edit the command, you edit the description RIGHT THERE. I wish more things supported this.
In before @Faraday: Her system does this. It's a drawback of the way Mu*s are coded that this hasn't become standardized. One can only hope.
But conversely, if you alias a command to another command then 'help' for both commands will give you the same help text
I think what you're getting at is that it's a good idea to provide a consistent pattern. For instance, I've dropped the '+' from all my help files, even if '+blah' still works.
I would disagree that all aliased commands giving the same help text is a bad thing; remember your data normalization! The more places data must be changed, the more likely it won't be changed correctly.
(That said, I object on general design principle to having command, +command, and @command do different things.)
That would just be mean to the players. It's unfortunate in Mush that we need 'help' and '+help', but is the only exception I can think of to these rules.
“If you wish to make an apple pie from scratch, you must first invent the universe.”
― Carl Sagan, Cosmos
@Thenomain said in Coming Soon: Arx, After the Reckoning:
@Sparks said in Coming Soon: Arx, After the Reckoning:
I think this is partly on Evennia, not just the Arx staff. (Sorry, Griatch.)
Specifically, Evennia generates a lot of the documentation automatically for each command...
In before @Faraday: Her system does this. It's a drawback of the way Mu*s are coded that this hasn't become standardized. One can only hope.
It doesn't exactly generate the documentation, but the docs are included and installed as part of the addon. I've had very poor experiences with documentation auto-generated from comments through the years. When writing code, devs don't generally have their "how do I explain how to use this coherently to a user" hat on ... if they even own such a hat in the first place.
That would just be mean to the players. It's unfortunate in Mush that we need 'help' and '+help', but is the only exception I can think of to these rules.
With Penn/Tiny you can't get away from @desc versus +desc, or WHO vs +who or help vs +help. It's just a legacy suckage you have to deal with. But why is Arx saddled with the same problem? I thought you could just override commands in Evennia like you can in Ares.
@faraday said in Coming Soon: Arx, After the Reckoning:
With Penn/Tiny you can't get away from @desc versus +desc, or WHO vs +who or help vs +help. It's just a legacy suckage you have to deal with. But why is Arx saddled with the same problem? I thought you could just override commands in Evennia like you can in Ares.
Most of the commands on Arx have @/+/no prefix all aliased, but it seems to be something that has to be aliased manually, and some of the commands are missing one of the prefixes. The fact that there's a time/@time difference and a home/+home difference is really weird and I'd say probably not a great idea as far as consistency goes. Everyone is kind of taught that everything is aliased prefix-wise but then there are these two random examples that are actively different commands.
I haven't actually figured out the particular rhyme or reason for which commands get added as @ to start or + to start or -- what.
@Sparks said in Coming Soon: Arx, After the Reckoning:
I think this is partly on Evennia, not just the Arx staff. (Sorry, Griatch.)
Specifically, Evennia generates a lot of the documentation automatically for each command; in a lot of ways, this is great; you include the documentation in the command source code, and a helpfile is made for it. No worries about documentation being out-of-date; you edit the command, you edit the description RIGHT THERE. I wish more things supported this.
But conversely, if you alias a command to another command then 'help' for both commands will give you the same help text; this leads to the home/+home, time/@time versus guards/@guards/+guards situation you describe. And additionally, since the coder is writing the documentation right there in the command, you... well, are getting coder-written documentation. Which (as a coder) I must admit is not always the ideal; sometimes you want an editing pass by someone who doesn't think in terms of code.
(That said, I object on general design principle to having command, +command, and @command do different things.)
I would say that it's really still a documentation issue, no matter where you put the documentation. The fact is that everyone playing the game -- including myself, who really loves it!! -- basically are muddling through, in a lot of cases, really unclear or confusing documentation. I know it's because of limited time and the fact that systems still change and develop regularly, but honestly they could use some dedicated to just cleaning up documentation. The team seems to lack a cleaner/organizer/admin.
I have overridden WHO, and anyone who tries to use both +desc and @desc should probably change one or both for the sake of their new users. The necessity of 'help' is critical, tho in thinking about it, perhaps renaming it to @help would be a good move. I don't think this outlier case is enough to disrupt what people expect, tho.
@Thenomain said in Coming Soon: Arx, After the Reckoning:
It's unfortunate in Mush that we need 'help' and '+help', but is the only exception I can think of to these rules.
I'm scrapping +help as much as I can in favor of +game, which pulls up the equivalent of news and +help. The original commands have 'Ahem, use +game please' or something on them. The first game I played on (a MOO) did this, and I found it helpful, so I stole it shamelessly, as it made sense at the time and still does: 'these are the files that you need to play the game', pretty much.
@Sparks said in Coming Soon: Arx, After the Reckoning:
Specifically, Evennia generates a lot of the documentation automatically for each command; in a lot of ways, this is great; you include the documentation in the command source code, and a helpfile is made for it. No worries about documentation being out-of-date; you edit the command, you edit the description RIGHT THERE. I wish more things supported this.
Thanks, the auto-help system is helped a lot by me myself always writing documentation whenever I write code - so me documenting my commands and then immediately converting that to an in-game help entry alleviates duplicate work. Many Evennia devs have taken up on this premise. While it doesn't write the docs for you, it at least makes it more likely that your code actually does what the help file says. It's certainly true that this may well lead to "dev-written help" though. While developer and staffer is often the same, that is something each Evennia game needs to consider.
But conversely, if you alias a command to another command then 'help' for both commands will give you the same help text; this leads to the home/+home, time/@time versus guards/@guards/+guards situation you describe. And additionally, since the coder is writing the documentation right there in the command, you... well, are getting coder-written documentation. Which (as a coder) I must admit is not always the ideal; sometimes you want an editing pass by someone who doesn't think in terms of code.
If you just alias one command to another (that is, create a command @alias with aliases +alias and alias), then they will get the same auto-help (since they are all actually just the same Command). My impression from the original question was however that there are multiple different Commands, each with a (slightly) different key - that means they are completely separate Commands and thus each get their own auto-help. How a game organizes their commands is up to them.
(That said, I object on general design principle to having command, +command, and @command do different things.)
Evennia itself is guilty of this in a few cases in its default command set (@desc/desc is the one that comes to mind), but our convention is that the @ is then the more capable builder-only version. This duplicity (in the default command set at least) is going away in Evennia 0.7 when we start allowing the developer to specify which prefixes (@, +, &, ...) Evennia will simply ignore (making @desc and desc effectively the same command even without an alias).
.
Griatch
@Griatch said in Coming Soon: Arx, After the Reckoning:
(That said, I object on general design principle to having command, +command, and @command do different things.)
Evennia itself is guilty of this in a few cases in its default command set (
@desc/descis the one that comes to mind), but our convention is that the@is then the more capable builder-only version. This duplicity (in the default command set at least) is going away in Evennia 0.7 when we start allowing the developer to specify which prefixes (@,+,&, ...) Evennia will simply ignore (making@descanddesceffectively the same command even without an alias).
.
I really, really hate having same named commands do different things and greatly look forward to that change. I just dislike all the different prefix conventions and would be delighted to see them go away, while being effectively backwardly compatible by letting whoever throw in their random prefixes that they are used to.
But yeah @desc/desc, time/@time, help/@help, home/+home/@home are all headaches.
@Roz said in Coming Soon: Arx, After the Reckoning:
I would say that it's really still a documentation issue, no matter where you put the documentation. The fact is that everyone playing the game -- including myself, who really loves it!! -- basically are muddling through, in a lot of cases, really unclear or confusing documentation. I know it's because of limited time and the fact that systems still change and develop regularly, but honestly they could use some dedicated to just cleaning up documentation. The team seems to lack a cleaner/organizer/admin.
I'd say they probably need a team member dedicated just to dealing with communications. Making sure there's a standard way to announce things, handling issues so that they're clear, creating theme files, and improving documentation.
@Thenomain said in Coming Soon: Arx, After the Reckoning:
the often confusing documentation was the first thing I asked about on the guest channel (and was called out for on it).
I really wish - not just for Arx but in general - people were more willing to accept criticism without getting defensive about it. Just because your game is good it doesn't mean it's perfect, and just because things can get better it doesn't mean the game sucks.
Some of the documentation isn't terrible, but a lot of it is, and what's worse, the available indexes for commands are so random. If you go to the commands page on the game's official website (I hesitate to call it a wiki), they're not in any kind of determinable order - sure, they've got category headers, but putting those commands in say, alphabetical order would be nice. The category headers are not intuitive.
The help files list commands often do not explain the context of various switches, or how the command it's explaining applies in context to the game itself. I genuinely worry that it's a big turn-off for newbies.
"If you stand for nothing Burr, what will you fall for?"
-- Hamilton: An American Musical
@Cupcake said in Coming Soon: Arx, After the Reckoning:
(I hesitate to call it a wiki)
It's not a wiki at all, so you shouldn't worry about hesitating. 
@Cupcake said in Coming Soon: Arx, After the Reckoning:
Some of the documentation isn't terrible, but a lot of it is, and what's worse, the available indexes for commands are so random. If you go to the commands page on the game's official website (I hesitate to call it a wiki), they're not in any kind of determinable order - sure, they've got category headers, but putting those commands in say, alphabetical order would be nice. The category headers are not intuitive.
The help files list commands often do not explain the context of various switches, or how the command it's explaining applies in context to the game itself. I genuinely worry that it's a big turn-off for newbies.
I actually forgot I even made them viewable on the website. I made them alphabetical. Thanks!
The rest of the documentation is admittedly pretty terrible. It'd be great to rewrite a lot of them eventually. It's just difficult to find the time - I'm not willing to postpone major systems for it, and there's four offhand I can think of that need to be done first.
@Tehom said in Coming Soon: Arx, After the Reckoning:
I actually forgot I even made them viewable on the website. I made them alphabetical. Thanks!
You're welcome. Thank you for doing that! It's going to make looking up help file details so much easier.
@Tehom I would posit that if people are struggling with current systems due to poor documentation, then clarification of current systems to ease use WOULD be more important than implementation of new systems that will suffer the same problems as the current systems. Ensuring that your players know how to easily navigate systems and files is probably one of the bigger things that should be prioritized (and often isn't).
@Miss-Demeanor said in Coming Soon: Arx, After the Reckoning:
@Tehom I would posit that if people are struggling with current systems due to poor documentation, then clarification of current systems to ease use WOULD be more important than implementation of new systems that will suffer the same problems as the current systems. Ensuring that your players know how to easily navigate systems and files is probably one of the bigger things that should be prioritized (and often isn't).
I have to agree here. Commands and systems shouldn't actually be considered finished -- or ready to launch -- without good documentation. It should be considered one complete package, not an addition.
That said, we're now crowdsourcing writing up clearer documentation, so.
On a different note, huge props to the player of the character who mailed Cristoph an alacarite weapon for the tournament prize, that seems to have gotten people an awful lot more excited over competing!
Plus that is a way cooler story/way to get an alacarite weapon than 'I ground out economic tasks for a few months'.
@Packrat You're making me wish I'd refined it more.
@Miss-Demeanor said in Coming Soon: Arx, After the Reckoning:
@Tehom I would posit that if people are struggling with current systems due to poor documentation, then clarification of current systems to ease use WOULD be more important than implementation of new systems that will suffer the same problems as the current systems. Ensuring that your players know how to easily navigate systems and files is probably one of the bigger things that should be prioritized (and often isn't).
I am reasonably certain that if I told every guy who was eagerly awaiting war systems for Dominion or everyone who wants PRP support or any criminal type who wants crime or every apothecary who wants recipes or every combat character who wants combat styles or everyone waiting for magic that all of these will be delayed by a year as I painstakingly look for the most unambiguous verb possible for each command and do my best to make everything as clear as possible through repeated submissions of help files for review that I would be murdered in my sleep.
Hey, hyperbole is my gig. I know false equivalence when I see it.
I deeply appreciate the load that most hobby coders face, but don't discount fellow staffers or, even better, fellow players. The number of people who are willing to do data entry for games they love is astounding.
