I notice in the patch notes that the custom/help folder has been added, and in the docu-wiki it's mentioned that help files are now all internal to the PHP modules through the $this -> help[] array.

Firstly, what lead to the decision to put the online documentation into the php files?  I intend to document all the commands properly for a guild of users that wants to migrate from IGN.  Documentation is by far the primary reason they are still using IGN, and they require a real level of online help for people new to chat bots instead of the meager user help BeBot currently has.  As it stands, I can add all the documentation I want to the PHP, but then it all gets overwritten and deleted when a new version of the bot is released.

An alternative would be that I get involved with the development and contribute docs to the SVN.  But I was hoping to elicit help from a couple of other friends in writing the text.  They aren't programmers and wouldn't be comfortable editing string values in the help[] array.


So that brings me to my second question.   Are you planning to use the custom/help folder (or a root/help folder for that matter) at all in the future?  I notice there isn't any code in the bot currently that reads from it.  What kind of format might be used if it were?  Any chance of an .xml file per module? I think it'd be better to separate documentation from code.  It'd also be fantastic if people implementing these modules would document them for the bot's online help instead of pointing people to the wiki, or even worse, just leaving the help regurgitating "no help found" for everything.

Thanks for the reply.  I agree that unifying the help file format is nice. I'll have a think about getting to work. It'll be some time before I get the chance to do much, but nice to know all this.

In the meantime I hope any new features added are being documented in the online help by everyone adding them!

No no I'm a coder myself, I'm comfortable with the mechanics, just not so much of the idea.  Although I see the logic of putting it in there, and understand the decision to do so, it goes against my desire for a few reasons.

One reason is for localisation.  I would prefer the docs to be seperate to allow the whole documentation to be localised into different languages easily.

But my main reason that I've decided I won't be contributing to the SVN is because the documentation I write is all in character (IC), and thus is not appropriate for the majority audience of BeBot.

For instance, here's an excerpt from the afk command:

AFK:  "Allows you to flag yourself as being away from your comlink.  The AI will increase security on incoming messages, locking any would-be request and notifying him or her that their transmission has been scrambled and will be unheard by you."

Thus, every single module, whether modified in function by me or not will have to be overwritten with one in the \custom\modules folder, as every command needs documentation.  And then every time the bot gets updated I will have to check whether the files have actually changed, and rewrite all my docs into the custom folders.

So....  Lots of work