Zugg Software :: View topic

Posted: Sat Aug 20, 2005 6:40 am

Hmm, I must be blind, I've only just noticed (after reading the Guru Forum, or somewhere), that I can actually edit the zApp documentation pages.

So I'll be trying to update at least any broken bits I come across, I hope you're ok with that Zugg.

(For example, the Collection.Insert page example made me scratch my head for a good long while, until I noticed that the text says: Index, Value, but the example was saying "hello", 1 .. Which I assumed to mean the params go the other way around.. So I've swapped them)

Now, which other item did I post a reply to...

Lady C.

Posted: Sat Aug 20, 2005 5:29 pm

Yep, definitely feel free to fix anything that you come across like that. That's why Guru's have edit access to the documentation ;)

Although at some point I probably need to implement a difference between zMUD Gurus and zApp Gurus. Then again, with a new MUD client written in zApp, maybe these two areas will naturally merge over time anyway. I might just go with a "Guru" icon and remove the "zMUD" part to make it easier to invite people with lots of zApp experience that want to help.

Posted: Tue Aug 23, 2005 6:35 am

Just another question about this.

In PerlScript, its essential to know which items are actually methods, and which are properties. (Since one can't assign to Methods, for example, I have to do $var->{Value} = 'foo'; and not $var->Value = 'foo')

Any ideas on how to standardize this info in the docs, or shall I just make one up?

Lady C.

Posted: Tue Aug 23, 2005 4:34 pm

That's going to be tricky. Not all properties are read/write...some are read-only, and in fact are implemented as functions rather then property "variables". I'm surprised PerlScript is so picky about this...makes me less likely to use it for much. Both VBScript and JavaScript don't seem to care (both just use the simple "dot" syntax var.Value).

I guess the best way to tell is that if something has arguments, then it's probably a function. Although there *are* a few properties that take index arguments (like collections) that might still be considered a property.

So what we need is not only a way to tell the difference between properties and methods, but to better standardize how read-only vs read/write properties are described as well.

In general, don't do anything to change the keyword or title of any of the documents, since that could break other links. If you have an idea on what to put into the body description of the properties and methods, let me know.

Also keep in mind that I want zApp to be accessible for the end-users who are simply trying to modify an application or write a simple plugin. So I have *purposely* left out some technical jargon in the documentation. I *don't* want to like words like "property" or "method" at the very top where the name of the property or method is displayed. What we need is some sort of code scheme that can be put in the upper-right corner, or somewhere like that. If we can come up with something reasonable, I can add a tag to the BBCode used in the Knowledge Base to make this easier.

So post your ideas here and we'll talk about it some more so I can come up with a way to make it easy. I'd hate to have you make a lot of text changes that need to be redone.

Posted: Tue Aug 23, 2005 7:50 pm

I'll put in a quick answer here as food for thought:
First, the docs as are wont be too much use for end-users, they need something more like "how do I do X", with lots of shiny examples, I myself also have trouble writing these sort of docs, so what we need is some non-technical user to have a look and say how much they understand. (Or better, set them a task or two, and watch how well they do at it. Theres a bunch of stuff on this at http://usability.gnome.org and an actual test they did at http://developer.gnome.org/projects/gup/ut1_report/report_main.html which is very interesting to read.

Anyhow, a further point.. I'm not sure leaving out info like property/method is a good idea, especially as it may frustrate/alienate the actual programmers. Maybe we could make a section in each page "technical details", or as a sidebar to each item, if thats possible. And some nice intro for end-users would describe how the docs are laid out, and indicate that this section can be usually skipped.

(oops ok, you said "not at the top", and not "not at all" ..)

A code scheme may work, though methinks that may confuse end-users even more (what do those symbols mean, am I suppsed to know?, etc..) Plain text is generally better, together with a "this is technical" label.

Anyfish, I'll think about this a bit and get back to you again..

Oh, and while I'm here, where did the docs for "Datasource" go to? ;)

Lady C.

SubAdmin Joined: 18 Nov 2001 Posts: 5182

I think adding a sidebar of quick tech notes would be a great thing. I know as an experienced programmer that often I am only looking for the types involved in any given function, method, or property. This includes both arguements and return values. Having those in a consistent location is useful. A bold text at the bottom of either this box or the description stating a Read-only status for properties is definitely a must. I think "borrowing" a little space from the related box for this sort of quick overview would be good, especially if this box could be given its own scroll bar. This would put the jargon in plain site for programmers, as they likely just clicked over there to pull up the page, but would be sufficiently unobtrusive that others would be drawn to th fuller descriptions in the middle of the screen.

I would suggest fixing the space for scroll bars beforehand so panels are not continously changing sizes on different help pages. This would also help to stabilize some of the zMud help pages that have huge related lists like the Command and Function reference pages that have the entire list, per type, in the related area. It makes for a lot of scrolling, I think when I was last looking at it, the bottom of the related list was actually much further down then the text in the main panel. Definitely too much scrolling.

Posted: Wed Aug 24, 2005 4:36 pm

The reference "tree" on the left is pretty much stuck how it is. To give it it's own scrollbar means turning it into an IFRAME, and I really dislike using IFRAMEs on this site (had a bad enough time experimenting with them with the Search page a while back). Besides, I'm not sure I see the difference between scrolling the left reference frame vs just scrolling the main page with the normal browser scrollbars. Maybe I'm missing something.

Back to the programmer information topic, I think I'm convinced by Castaway that I should just include the full information in the main header for the topic. It is easy for me to add custom BBCode to the knowledge base. So what I could do is come up with a BBCode for properties, methods, etc and standardize how the information is displayed. Then when I create a topic I'm just entering the property or method definition and allowing the BBCode to handle how this is formatted and displayed.

So perhaps we can turn this into a discussion of some examples of how you'd like to see this header displayed for properties and methods. I'd personally like to keep the hyperlinks for the data-types, although I might make them popup boxes instead of taking you to the specific topic for the datatype itself. Right now it is actually a pain to enter these headers since I have to use the link syntax to link each data-type. With a custom BBCode entry I could just come up with standard abbreviations for each data-type and let the BBCode expand them to the proper links.

So maybe something like this:

[ prop ] name: type [ / prop ]
[ meth ] name ( arg1: type, arg2: type ... ) : optional-result-type [ / meth ]

where each "type" was something like "i" for Integer, "s" for WideString, etc, and then I just put modifiers on the type like "ro" for readonly, "out" for var-passed arguments, etc.

If I have a standard way to enter this information, then it would be easy to come up with a good output format based on CSS styles for displaying the information.

Yeah, I know, I said "not at the top". As you well know, I can usually be talked into changing my mind...wouldn't be the first time ;)

Posted: Wed Aug 24, 2005 8:25 pm

Beginner Joined: 09 Aug 2005 Posts: 17

How to scroll in a DIV: http://www.devx.com/tips/Tip/14152

Posted: Fri Aug 26, 2005 11:38 pm

Hmm, I didn't like this statement at the end of that article:

Posted: Fri Aug 26, 2005 11:57 pm

yes they are [supported by firefox]