Is the scripting wiki helpful to you?

*snort*

You're a funny man.

llSetColor : 'llSetColor' '(' color ',' side ')' ;

color : vector { range_check($1, <0,0,0>, <1,1,1>; }

vector: vector_constant | symbol | vector_expression ;

vector_constant : '<' float ',' float ',' float '>' ;

...

Over in the scripters forum, we scripters were asking ourselves whether the current wiki is helpful to beginners / dabblers / would-be scripters. I had the radical idea of going somewhere where such people actually hang out, and asking them, instead of guessing.

The opening para of the wiki has since 2007 contained these words: "scripters of all levels" . That would seem to make stakeholders of some people like builders who try their hands at scripts.

I'm happy if the people I see saying "it's fine as it is" are builders. Cause that means we're done here.

I'm disturbed by some phrases I'm seeing describing non full-time scripters; phrases such as "mickey mouse manual", "idiot" and "dumbing down the wiki" implying that they are dumb. That making sure it was useful to them would "screw things up."

Builders are just as skilled as we scripters are, only they have their skills in another area, but other than that, I respect them immensely. They aren't dumb. I'm in awe of what they make; I can't even rez a prim straight.

I have suggested that one thing that could be done to solve the conflict in the wiki's mission and goals would be to remove the words "scripters of all levels." I'd also be okay with that, because then people like me and Eren and Chosen would know that thoughts for an accessible wiki can turn to other methods, other venues.

Cheers!

I think there's a bit of confusion hidden underneath this comment.

Some people read that and say "a beginner who doesn't know anything is still a scripter... of beginner level".

Others read that and say "this is suitable for scripters, not people who aren't familiar with programming".

If it said "medical practitioners of all levels" would you assume that included people who'd watched a lot of "ER", or would you assume that meant "nurses and paramedics as well as doctors"?

I think the llSetColor(...) example is too simple and it can not be used to explain how that could be rewritten cleaner/simpler/better/more correct/whatsoever ... See what i mean when i choose llSensorRepeat() instead of the above function to explain "the best syntax":

It was said, that this is a "clean syntax definition":

While this is what we have right now in the wiki:


Assume, we would make the compromise and write it down like this:



It may be cleaner, but now while i see it, i dislike it, although i stated earlier, that would be my favorite syntax. I find my eyes flipping repeatedly between the "syntax line" and the parameter declaration lines to understand which of the floats has which meaning. The wiki makes it apparent and easy understandable (i talk for me only here).

So my question is: What would be the true benefit of the "clean syntax line" ? And what makes the current presentation (in the wiki) be considered as more evil ? How would a beginner programmer benefit from the clean solution ? Is there some theorie behind the scenes, which clearly explains that ? (learning psychology or something alike ? ... )

Argent, you may be getting to the core of things. It could be just that wording that is causing the conflict, and that needs addressing -- or removing.

What i clearly hate about hypertext is, that a link to an external source does not tell about the quality of its content. So it is up to the editor to ensure that the hyperlinks are choosen carefully. For me it is very unpleasant to see a text with tens of hyperlinks to this and that and further reading. I still have to flipp forward and backward to check for myself if the hidden information is usefull to me. In that sense adding a "hyperlink to idiot notes" is questionable in two ways:

1.) Who is addressed in an "idiot note" ?
2.) What would be the content of such a note ?

But i really would appreciate, if each function would be accompanied with a hyperlink to a section "concepts and examples" where i would be informed about just that , the concepts and how they should be applied (maybe an optional "best practice" section)

I really do not think, that the wiki should be adressed to people, who insist of making their job without learning their tools. In that sense i would appreciate a help section (like the concepts section attached to each function) which makes it more easy to learn the scripting in an efficient way.

From my own experience in teaching i often found the "learning by doing" approach the easiest of all to give my students a good overview about the concepts, while they would happily dig into the "reference guides" after they "got the overview". Thats what i whished to see in the wiki. And it is clearly ok for me to hide the "concepts and examples" behind a hyperlink as long as it is labelled appropriately...

I wasn't suggesting links to "idiot notes", I was suggesting links BETWEEN the user guide and the reference manual... both in the Wiki... rather than trying to turn the reference manual into a user guide.

Would a "concepts and examples" section be something that you consider as being part of the user guide ? ok, then we talk more or less about the same thing. Sorry for having missinterpreted your words!

Everyone knows that I love to see new people learning, no matter what the skill set. But I do not see anything we are discussing having an impact on the mission statement. Nor do I see anyone saying that they do not want new people to learn or that they want to keep the wiki cryptic and indecipherable. The wiki is much, much more then just the "dictionary" portion that defines the llFunctions for example. As pointed out here, there are sections with tutorials on various aspects including the basics. There is no reason that this section can not be enlarged and new content added.

Just as I stated in my "Spanish" post. An English/Spanish dictionary does not teach someone how to speak Spanish. It is used only as a reference to define the meaning of individual words. This is exactly what the individual llFunction pages do. To learn Spanish you need to do much more then buy a dictionary, this applies to LSL also. Take classes, read the tutorials, ask questions in the forum. Once you do that then the individual llFunction pages begin to make sense.

This is no different then the advise given here everyday in any of the Content Creation Forums. When people with no previous experience ask questions on using a program like Maya, they are encouraged to first watch the tutorial videos, learn the basics and then the advice given on how to do a particular function will have context.

Almost every page of a good reference manual would have at least one example... more for complex functions... and must have a text description of what the function does. Concepts, use cases, and more complex examples that address specific use cases... those would go in the user guide.

Perfect! Then isn't the wiki allready in a fairly good shape? It just lacks completeness in the sense you describe: not every reference page has an example section and some conceptual pages (hyperlinked from the reference pages) are missing. Wouldn't it make sense to just complete the wiki in that sense?

Ah, the java tutorial trails just come into my mind... It would be awesome to setup something similar for LSL, so that from the trails we can reach the reference pages and from the reference pages we can reach the trails... that would really be cool

Is it that what you are talking about when you write "user manual" ?

Maybe it even makes sense to address performance in a sensefull manner ? I often would like to know if using a specific function has potential for lag. Since i do not know how to measure this in a reasonable way, it would be good to see something mentioned in the reference pages.

Having some kind of narrative structure (it doesn't need to be as rigid as "Chapter 5, physical objects..." or some other book-like form) that organizes the use cases into a guide is important. I believe that the closest the current wiki comes to that is category pages. But, yes, that's the direction I see as most useful.

Performance is a useful conceptual section, yes. That's something you might expect to see as a chapter in a good user guide, or it might be better to make it a common section for the reference manual... at least for functions that have unexpected performance impacts like llRezObject().

The links in a well-edited, semantically structured and truly accessible web site should be chosen carefully as a matter of course. Also I had the impression that, in essence, a quality web resource is what is under discussion here so surely there will be no call for links to other web sites?


My apologies for the slack terminology but 'idiot notes' would be for the benefit of newcomers not just to LSL but to scripting in general: there is absolutely no reason to expect that a resident will have any prior knowledge or experience of scripting whatsoever but there is every reason that he or she may become interested in scripting purely through their involvement with SL. The point would be to separate rich detail that a newcomer to scripting may require from the bare bones that an experienced scripter might need for reference.

You name it and I for one would like to see it explained in detail, with examples of good usage as well as a comprehensive exposition of common errors where possible and absolutely no prior knowledge taken as granted.


I was under the impression that the Wiki was about learning the tools - or did I get it wrong and it is actually a reference for experts? LSL might be fairly accessible to those with prior knowledge and experience of other scripting languages but it is clear as mud to residents like myself who barely understand programming but nevertheless are seeking to improve their SL experience with a little invention.


I would like to see a comprehensive, stand-alone resource that does not even require a teacher: everyone has his or her own way of learning and sometimes the teacher's own method can be as much of a hindrance as a help - especially if they aren't actually in the room or online.

There is no reason why a Wiki on scripting for SL should not be constructed as a viable resource for those who know absolutely nothing as much as those who virtually know everything without compromising the needs of either group.

By the way, Argent, I didn't mean to imply that you were suggesting any such thing either. I only meant to draw attention to what should be evident to anyone using the web or discussing a collection of documents such as the Wiki. Users of all levels -and 0, zilch, niente, yok is just as much a level as any other - should be able to make use of it as a resource thanks to the inherent qualities of hypertext.

The argument that people who know nothing about scripting should just leave it alone is like saying those with no design sense shouldn't build - so much BS.

I do not see anyone saying that here. I do see people saying that you need to learn the basics, that there are multiple resources available to learn those basics and that people want these resources expanded.

I just do not think, that it is usefull to address those people on the reference pages, who have no slightest idea about scripting (for whichever reason). In that sense yes, i think, the reference pages are NOT good for the zero-level scripter.

And for sure i think the wiki does/should support learning (in the concepts/examples/guideline documents) as well as referencing (in the reference pages).

I also wonder if the zero-level programmer would really want to start digging for solutions on the reference pages... Maybe they search for particular solutions to their problem. Then they should end in the examples/concepts parts of the wiki, not in the reference pages.

But after they have read the "introduction to LSL and how the wiki can help to solve your problems" sections (which can be very short at the end), they will be well prepared to understand the reference pages too (and know about syntax and types and such...) at that time, they have allready started to learn and are not any more zero-level ...

By time when the skill level grows, they might end up in "reference page hopping" which is fully ok, because obviously they have now understood the basic concepts and may carefully be titled as "experts..."

Hence i think, the wiki is not too bad, it just lacks completeness and conceptual information. So i guess i am conform with many of the contributors here, no ?

regards,
Gaia

I don't see anyone saying that.

The basic point I would like to make about learning is that you just cannot anticipate where or why someone might get involved in a subject. The sine qua non of a good reference is to supply all of the necessary information to answer questions and, in my opinion, that involves explanation of every detail of scripting pertinent to LSL in this case since many residents are quite ignorant in the field. Prior knowledge of other programming languages such as C++ or Java should not be assumed, for example.

This is particularly important in terms of SL where the greater number of us reinforce the limits of the medium through our ignorance not only as consumers but also as creative dilletantes. I would go so far as to argue that we actually define the limits.

More lag anybody? Have you had sufficient or shall I dole another slop on the plate? (It's no mod, who's gonna notice?)

My apologies if I am beginning to whine, but residents without prior knowledge, training, experience or whatever have much trouble coming to terms with LSL and I truly believe this is not apparent to residents who have been gifted by training or natural talent with an understanding of the grammar and syntax of scripting.

Reading the Scripting Tips Forum, I sometimes feel like Johnny Foreigner being yelled at by a well-meaning missionary who seems to feel that if he shouts loudly enough, I will eventually understand the Queen's English by the miracle of sheer volume.

I do:


Admittedly Chaz is suggesting that we should look elsewhere and Gaia is consistently assuming that the Wiki just isn't an appropriate place to start (as Jesse observed with her comment regarding learning the basics). But why should we look elsewhere? Despite both arguments, my opinion is that a truly workable Wiki for SL residents would address the needs of those with little or no experience from scratch as well as the needs of experienced scripters.

My reference to hypertext was intended to point this: thanks to hypertext, there is no end to the potential depth of a Wiki that truly aims to support scripting in SL.

Does anyone posting to this thread assume that I haven't looked at all of the resources pertaining to LSL?

As pointed out a few times. The wiki is much more then just the llFunction definition pages. Look at the links provided in the tutorial pages. They specifically target people with no previous scripting knowledge. With the knowledge gained there then the llFunction pages make sense. The wiki is ALREADY designed for everyone.

All i say is: Do not attempt to do THAT on the reference pages. Do it in the concepts pages and in the guidelines. And refer to the concepts pages and to the appropriate documentation from the reference pages and vice versa.

I even proposed to create a set of LSL tutorial trails similar to what i first have seen in the java documentation at http://java.sun.com/docs/books/tutorial/ (the idea of tutorial trails might even be older, i don't know that) So where is the disagreement ???

Programming is a complex topic, and it takes a certain amount of effort and time just to learn how to program. This effort and time is not optional, it's not something that can be avoided by improving the documentation. It's simply due to the fact that software is almost inherently the most complex "stuff" that human beings have ever created. You can make it easier to learn, but you will always, no matter how easy you make it, have many many people with trouble coming to terms with it... simply because of that complexity.

You can eliminate most of that complexity, create a language with no variables or no loops or no non-volatile state, but once your programming language becomes turing-equivalent there's no alternative to actually learning how to program to really use it.

This is not saying that people shouldn't learn to script, it's saying that "learning to script" means getting that training.

As someone who has been involved in the Scripting Tips for an extended period I have only seen this a couple of times. Anytime anyone who exhibits an interest in learning(as opposed to just looking for a free script) has been shown anything less then a warm reception, the person who is talking down to the new person has then been given a serious talking to by the elders in the community. I know I have personally done this a few times.

There's one kind of person who gets routinely tossed on his ass in the scripting tips forum.

That's the type who comes in with no interest in actually writing anything and expects the forum to write a custom program for him by osmosis.

Perhaps Ephraim is confusing this kind of person with someone who's actually looking to learn.