Zugg Software :: View topic - Updating the Knowledge Base -- Integrating Comments and Examples

Posted: Thu Aug 21, 2008 9:31 pm

There has been some discussion recently as to the state of the documentation. While it is good, it can be better; especially if we integrate the comments that apply directly to KB articles as well as relevant discussion and examples that are interspersed between the forums.

I will be tackling #EVENT and the Lua Tutorial first since they are areas where I already have some thoughts on what can be done to enhance the documentation.

Beyond that, I am open to suggestions. Suggestions on what areas you think need the most work will help me to prioritize the work.

For specific topics, please add comments to them and I will work on integrating those comments. If you prefer, you can just like forum discussions that you think provide key insights or good code examples, and I will work on integrating it as well.

Now I'll admit up front, that progress may vary depending on time availability so your comments and assistance will help drive, in large part, how quickly it gets done.

If you have any questions or comments, please post them here.

Enchanter Joined: 09 Sep 2007 Posts: 605

Tech, when you'll work on script examples, could you add "advanced scripting" paragraph with more complex scripts, like it has been made in the article for #TRIGGER command: #TR?

Posted: Fri Aug 22, 2008 8:08 pm

That shouldn't be a problem, but what the question is what those 'advanced' scripts should be.

If you have a favorite example, then please link to here or in the comments for that topic.

I'm also planning to add something under tutorials, or it's own category Advanced Concepts and Scripting. For example it will include walkthroughs of some of the more complex myself and others have done.

For example I have some code that does a 3 color gauge, and that is extensible to more colors if need be. Another more complex is a click-driven status window menu using MXP and Events, and creating an MXP menu from ANSI text while still maintain the color.

I'll start the things I've code and let others make suggestions for what they'd like to the mix.

Enchanter Joined: 09 Sep 2007 Posts: 605

Tech:
Actually, under "advanced scripts" I didn't mean publishing complete scripts that could do crazy things (although it would be great! Maybe under the "Tutorials" node?). Sorry, I've used the wrong words, really. I want to say "show how to use optional arguments and other stuff" - here is one of the best pages in the whole CMUD help: mxp

SubAdmin Joined: 18 Nov 2001 Posts: 5182

In some ways it is too bad you can't look into the zMud Beta forum. A few years ago when I was working on the zMud help I was going to build an entire databasing tutorial. The cornerstone of that was going to be one of my scripts that did things like making sure the window was open, controlling duplicates, handling the complex 'ROM' affects data, and then some. The basic consensus, from the beta community at that time, was that is far too advanced to be in the help.

The thing to learn is that we have to be careful just how complex we get in the examples. In general the examples directly in the reference topics for each command/function should show proper usage, and possibly all proper usages. Some examples should contain other commands/functions commonly used with the specific item for which the help covers. The use of those commands/functions should be crosslinked, by my standard they only need to be linked to appropiate reference the first time they appear on the page.

Getting into more advanced and complex things really is something for the tutorials area. If anyone wants to write a complete 'how to' for something that is beyond what is appropiate in the help, then there is a fair chance it would be published as a tutorial. I believe it requires adminstrative access to approve the publication; which would mean Zugg, Darker, Kjata, or myself would do it.

If you pull up the tutorials section of the documentation for zMud you will find that nexela is listed as the puiblisher of many tutorials. Perhaps a way to link a help to a related tutorial is needed, but first a few useful tutorials are needed.