Zugg Software :: View topic

Posted: Wed Oct 04, 2006 5:14 pm

As I mentioned in some other posts, I'm starting to focus on putting together the help files for CMUD. I think this is a big priority before a general announcement and will help beta testers use CMUD more effectively.

Since CMUD uses the same zScript language from zMUD (with enhancements), it's pretty obvious that I'll be converting many existing zMUD help topics over to CMUD. Topics for various #command and %function references will be transferred and updated. Then I'll be writing new topics on the new CMUD user interface, packages, modules, sessions, etc.

CMUD will not be using the normal Windows help system. I developed a help system when I wrote zApp that I want to use for CMUD. If you have played with zApp at all, you'll remember the DocView program. This program would display a database of HTML help topics, but allows the database to be updated by the remote web site.

The idea is to keep the documentation over in the Knowledge Base synchronized with the local help database on your computer. I can do all of the creation of help topics and editing on the web site (and Gurus have access so they can help too). Then these topics get downloaded into your own local help database to use within CMUD.

So, this is the architecture that I'm planning. You'll see help topics appear first on the web site over in the Support/Documentation area. Then with 1.09 or 1.10 you'll have the software within CMUD to download these help files and display them.

Feel free to post your ideas or suggestions for the new help system. Feel free to discuss what you didn't like about the zMUD help system and what you'd like to see improved. And if you have played with the zApp DocView program, please let me know if you have any concerns about using a system like this with CMUD.

And, if you know of any magical way that will help me write these help files more quickly and easily, please let me know...I really hate writing help files and they seem to take a lot longer than they should.

Wizard Joined: 10 Oct 2000 Posts: 1551 Location: Australia

I never really played with zApp or it's help system so I'm not sure how it quite works, but my suggestion (if it doesn't have it already) is synchronize on demand...

Generate a hash for every help file in the database then when a user goes to browse an entry, query the server to see if the local hash matches the remote hash. If they don't match, pull down the remote entry and add it to the local database, rather than pulling down every changed help file when someone might not ever use it.

So I guess have 'update manually', 'update automatically once a month', and 'update automatically on demand' as the options?

GURU Joined: 23 Dec 2000 Posts: 4834 Location: USA

SubAdmin Joined: 18 Nov 2001 Posts: 5182

I am definitely looking forward to the more synchronized help system that zApp showed possible. I think the most important thing with help is to be able to get it quickly. Many of the changes I made in the old help were to reference the indexand contents in such a way that using a very simple word you could be put on the right track for the specific word used in the script language.

I always kept in mind a moment from when I was in high school; my French teacher asked why an intelligent person such as me, studying French, exhibitted so much stupidity in learning it. My reply was, "This is my 6th language. I already know English, BASIC, Assembly, Pascal, and fair bit of Russian." He stated that most of those are programming languages that are based in English; he didn't quite understand how a single misplaced character can be the source of problems for many 'sentences' thereafter.

Most of the examples that are contained in the old zMud help for both the function and the command reference files should work in CMud, a few will have to be adjusted and let the Gurus handle that as people find them; however there are still many useful items off in the other sections of the help. Sifting through the rest is very likely right out at this time, I would suggest just trying to get the reference portions on line immediately with at least the same level of cross-refrerencing as the offline zMud help has. Being able to do related and some sort of 'maybe you wanted' type of referencing is very important, anything that improves a users ability to find what is needed for the solution is important. I might even suggest just producing a means for Gurus to add reference words and letting it develop from there.

After that try and see if any other portions from the old help are still useful. Many of them should be, but they will need minor rewrites in various areas to conform with the new interfaces. Quite often my usage of double-quotes around %nn references will be the only problem.

Posted: Thu Oct 05, 2006 3:56 am

Rainchild: The updates are "on demand". It's similar to the Package Library. You click a "Get Updates" button and it returns anything changed in the database since the last update retrieval. Retrieving individual items isn't feasible since there are often changes to the cross reference and index links that also need to be updated.

Delegation? Would be great if there was someone to delegate this to. But unlike zMUD, there is really only one CMUD "Guru" right now and that's me. So I'm the only one who can write the new help files.

Converting the #command and %functions is something I should be able to automate. But I consider that the least important part of the help files. After all, you can already load the existing zMUD help file to look up a command or function, and that information is mostly the same for CMUD. I think the most important parts of the help file are probably the sections on the completely new stuff, like packages, modules, etc, and documentation for the new settings editor, window docking system, shared package library, etc. Plus a whole section on the compiler and how stuff is different from zMUD scripts.

In other words, it's the CMUD equivalent to the various "Getting Started" topics that I need to start with, and I'm about the only one who can write those sections.

Posted: Thu Oct 05, 2006 8:20 pm

stupid question time:
If you are on the train, and without internet access, and doing some offline coding and need to look up something in a help file, does this mean that there is NO help file to see unless your connected to the internet?
Not sure what was meant by the whole download on demand etc stuff...

Posted: Thu Oct 05, 2006 8:45 pm

No it will view the locally cached copy. There will always be one once it has been made, it's currently not being distributed in the beta package.

Posted: Thu Oct 05, 2006 8:50 pm

kewl, just wanted to make sure :-)
Just need check for an update before you go on the road just in case there was a change. (If you haven't updated in a while that is)

Thanks

GURU Joined: 24 Sep 2000 Posts: 1237 Location: USA

I would like to see the helpfiles like the php help files - each has a comments form that you can use to submit additional (moderated) information to. See http://www.php.net/manual/en/function.highlight-string.php for an example.

Not questions - just more examples, clarifications, notes, common uses, etc. It's impossible to think a single (or even a dozen) users who wrote documentation for commands and functions would think of every possible use/example/explanation of them.

Posted: Thu Oct 05, 2006 11:35 pm

I'm afraid the Comments will only be visible on the web site. There is a button in the help screen within CMUD to jump to the same article on the web site to view the comments. Downloading and storing the comments properly is a real pain because the comment system is tied into the forum system, and I don't want to overload the help system with all of that.

In any case, if you go over to the existing documentation in the Knowledge Base, you will see that you can add comments. In fact, someone added a comment today when I was in the middle of editing the initial CMUD Manual topic about a typo and Taz responded and fixed the typo before I realized it.

So yes, comments are important and are already implemented...they just won't be downloaded into your local helpfile cache.

Also, before someone else asks the other obvious question: "Can I print the help files?" Currently you can only print an individual page of the help file. However, in the future it should be possible to write a routine that will walk through the topics and print them all, or export them to a file (like an RTF file).

The other faq: "Can I search the help files?" is yes. Just like with the zApp DocView, there is a Search field that you can use to find all topics that contain a particular text string.

And yes, there is support for "related topics" just like the online version.