Register to post in forums, or Log in to your existing account
 

Post new topic  Reply to topic     Home » Forums » General zApp Discussion
Castaway
GURU


Joined: 10 Oct 2000
Posts: 793
Location: Swindon, England

PostPosted: Sat Aug 20, 2005 6:40 am   

zApp Documentation editing
 
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.
Reply with quote
Zugg
MASTER


Joined: 25 Sep 2000
Posts: 23377
Location: Colorado, USA

PostPosted: 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.
Reply with quote
Castaway
GURU


Joined: 10 Oct 2000
Posts: 793
Location: Swindon, England

PostPosted: 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.
Reply with quote
Zugg
MASTER


Joined: 25 Sep 2000
Posts: 23377
Location: Colorado, USA

PostPosted: 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.
Reply with quote
Castaway
GURU


Joined: 10 Oct 2000
Posts: 793
Location: Swindon, England

PostPosted: 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.
Reply with quote
Vijilante
SubAdmin


Joined: 18 Nov 2001
Posts: 5182

PostPosted: Wed Aug 24, 2005 12:06 am   
 
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.
_________________
The only good questions are the ones we have never answered before.
Search the Forums
Reply with quote
Zugg
MASTER


Joined: 25 Sep 2000
Posts: 23377
Location: Colorado, USA

PostPosted: 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 ;)
Reply with quote
Kiasyn
Apprentice


Joined: 05 Dec 2004
Posts: 196
Location: New Zealand

PostPosted: Wed Aug 24, 2005 8:25 pm   
 
Zugg wrote:
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.


i believe there is actually a way of doing this with a DIV tag... i just can't remember how
_________________
Kiasyn
Owner of Legends of Drazon
Coder on Dark Legacy
Check out Talon, an easy IMC connection.
Reply with quote
cmurphy54
Beginner


Joined: 09 Aug 2005
Posts: 17

PostPosted: Fri Aug 26, 2005 7:05 pm   
 
How to scroll in a DIV: http://www.devx.com/tips/Tip/14152
Reply with quote
Zugg
MASTER


Joined: 25 Sep 2000
Posts: 23377
Location: Colorado, USA

PostPosted: Fri Aug 26, 2005 11:38 pm   
 
Hmm, I didn't like this statement at the end of that article:
Quote:
Note:OVERFLOW is supported by IE4+, but not by Navigator.

Does anyone know if the scrollable DIV tags are supported by Firefox? I'm not going to use something that is IE only at this point. Then again, I just consulted my CSS book and in the compatibility table, the Overflow tag says it is supported by everything except IE4. Maybe I'll just have to test it myself.

Anyway, thanks for the link. Learn something new every day!
Reply with quote
Kiasyn
Apprentice


Joined: 05 Dec 2004
Posts: 196
Location: New Zealand

PostPosted: Fri Aug 26, 2005 11:57 pm   
 
yes they are [supported by firefox]
_________________
Kiasyn
Owner of Legends of Drazon
Coder on Dark Legacy
Check out Talon, an easy IMC connection.
Reply with quote
Display posts from previous:   
Post new topic   Reply to topic     Home » Forums » General zApp Discussion All times are GMT
Page 1 of 1

 
Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
© 2009 Zugg Software. Hosted on Wolfpaw.net