Zugg Software :: View topic

Wizard Joined: 22 Mar 2007 Posts: 2320

I've debated with myself several times on the best way to provide documentation for library packages. Currently, users getting packages from the library have to rely on the description in Package Properties, and by reading the actual code. This is inadequate if we want relatively unsophisticated users to pick up Cmud and use ready-made packages for their mud of choice. For a while, I considered creating a package which would provide a documentation command, allowing package writers to create documentation in a consistent method, displayed by an alias which will work for any package following this protocol. But I gave it up eventually when I decided to avoid packages depending on the presence of other packages. I've put documentation within my main aliases, displayed when the parameter 'help' is added after the alias. But that doesn't help document functions, or the general use of a package, or various other things. So I am revisiting the idea of an external package to display documentation.

The question is: would package writers actually use something like this? And could unsophisticated users be led to load an extra package so they can read the documentation?

Here is the concept. Documentation would essentially be string variables, perhaps formatted with MXP. Packages would register the variables with the document package, including a reference name and full path to the variable. An alias, doc, would find the reference name in the registry and display the text in the variable, e.g. doc skillname.

Nice additional features: multiple reference names could refer to the same doc variable. The doc package could define an MXP element making it easy to 'hyperlink' to other document reference names. Users could create and register their own 'documents' for their own use. Registration would be done by events, the variables themselves accessed by full path, reducing scoping problems. Packages would not have to be global. If 'doc' cannot find a name in the registry, it could see whether it is the name of a module; if so, it could look for a variable named 'doc' under that module. This would be somewhat like the function of index.html.

So, if such a package existed, would it be used? I certainly don't want to start something like this if there's no interest. And if there is interest, I'll welcome input on implementation.

Posted: Tue Sep 02, 2008 5:04 pm

I actually already have a "package documentation" item on my to-do list. It isn't as fancy as what you described. I was planning to just add another tab to the package properties for the documentation that would accept HTML text (and provide the same WYSIWYG editor as the main editor window). This would be the default page that would show when you look at a package properties.

Some of your ideas are interesting, but I'm not sure how many package designers would use a system that was too complicated. Some people would want to document every detail of each alias, variable, etc, while other people would just want "how do I use this?" documentation. The "Notes" field for aliases, variables, etc already provide a way to give technical documentation about a package. So it seems like the biggest need is for the "how do I use this" documentation that needs more than you can currently do with the simple Description field for the package.

Wizard Joined: 22 Mar 2007 Posts: 2320