Is the scripting wiki helpful to you?

Learning anything takes time and effort. Building. Animating. And all skill- sets that are just as complex as scripting.

So I totally agree, and expand the thought a bit by adding that improving the documentation can help, by making sure that the documentation or lack there-of (or it's being scattered all over hell's half acre...) doesn't unnecessarily *add* to the effort and time.

This I think all of the principles here can agree to.

No one is saying that the llFunction definitions should not continue to be improved and that more, clear, concise examples need to be included. The only disagreement I see is that if you click on the definition of llSay, should you then see 3 or more pages explaining states, events, strings, integers and floats. Individual pages are already there that define these basics and in fact if you click on "string" in the llSay page, it opens the page for "string".

If you have never written a script thou the page on llSay will not tell you how to do it. You need to learn the basic skeleton structure of a script and it's components. You need a state with opening and closing brackets, you need an event inside that state to trigger the actions, you need to define the string that will be said and then you can use llSay.

If we are discussing potential improvements to the Wiki then I think it could be improved in terms of structure. I have been almost a daily resident for 20 months and, having had frequent recourse to the LSL Wiki, I would insist that it lacks intuitive structure.

The information just does not occur where it should and, when it does, it is impenetrably incomplete.


I would have hoped for that here because SL is an environment that actually stimulates me to learn. As an accomplished artist in 2D, I am constantly surprised by the 3D advantages the virtual world provides. Likewise, scripting has never appealed to me more than in the context of SL. I don't see the point in getting a dry course in C++ or whatever just to improve my understanding of LSL.

There is a great deal of controversy over Linden Labs' possible baiting of conglomerates and corporations for investment to keep SL afloat at the moment, at the expense of residents enjoying the virtual world for what it is: a creative and cathartic environment. Frankly, I see an independent, self-supported series of modules demonstrating how to script from scratch as being one of the cornerstones that might actually help SL residents keep a hold on their virtual environment.

Please realise that i distinguish between reference pages and concept pages. I have never said, the wiki is no place for beginners. I have only said, that the reference pages are a bad starting point for beginners and should NOT be optimised for making everybody happy (which simply can not be achieved anyways as we see from this thread

Sorry, i can not say anything else but:

* If you are a programmer, you typically first go and learn the syntax (which may be an easy task for a programmer in the case of LSL), then it may well be that you forward to the reference pages and only when in doubt consult the concepts pages. (i personally would prefer to read a bit about the concepts before moving on to programming, whether i am a developer or not...)

* If you are a non programmer, you first should go to the concept pages, then you should learn the syntax and eventually the reference pages will become a usefull resource of information for you.

At no time you need to leave the wiki. All is there or at least should be there at your fingertips.

That is what i am talking about. And i still do not see any disagreement with your ideas Ephraim ... And please can you point me to the observation of Jesse about my comment regarding learning the basics ?

That's cheap, Argent.

Who pissed in your Wheaties this morning?

His comments were not meant to have any negative connotations. The same thing actually went through my mind and this is why I mentioned in my post that the the exception to a warm welcome was when someone asked for free scripts. I think we both thought this was what you witnessed when you mentioned seeing people being yelled at.

Please understand that Argent, myself and others sacrifice hours of personal time doing nothing else but trying to help new people learn. We want to make the process easier for everyone and would be thrilled if every single person in SL became expert scripters. This is why I do not have a store and give away scripts that would be worth serious money. This is why the scripts that Argent does sell have mod permissions and anyone can open the scripts and see them.

What if.... (and if this is a bad idea, I won't fight for it, just wondering myself even, too...)

What if... on the portal page... there were a prominent link that said something like "How to do various common things." (insert better wording here.)

And if that link took ya' to a page that listed a number of links for basic things people often want to do... like, say something, start or stop an animation, start or stop a sound, read a notecard, change colour, change size, present a "menu" ... (list could go on and on.) Many of these links could just point to the already excellent examples under LSL Examples and Script Libraries. Some, we'd need to come up with examples for.

On the start and stop animation page, whoever wrote that would have to explain that ya' can't just start and stop an animation -- permissions are involved so you gotta read the sample page of permissions as well. Etc.

Each page could link where appropriate to the reference page for the function in the wiki, and perhaps vice versa (I'll leave that for others to decide.)

These pages, aimed smack dab at beginners and dabblers, would be written in plain English, and offer mini, self-guided "on the spot" tutorials to someone wishing to do whatever specific task at hand they are facing in-world. I'm thinking the pages would be task oriented rather than function oriented, cause that is the mindset that such people will be in when they come looking for help on "how to start an animation."

These pages would be part of the portal, rather than part of the LSL reference wiki.

And a pro coming to the portal looking for info on starting an animation will still be able to make a beeline for the function page to check what version of the SL client supports how many anims playing at once.

I've just thought this out very roughly. So I like I said, I'm not even prepared yet to back what I've just written 100%. Just tossing it into the pot.

I never suggested you need to get a "dry course" in anything. And I wouldn't suggest my worst enemy try to learn programming in C++! I'm suggesting that there are some deep and fundamental concepts that are common to all programming, and you have to learn these concepts, and some people have a lot of trouble with them.

There are all kinds of introductory programming texts built around languages that are anything but dry and boring. If the introductory material in the Wiki doesn't cut it for you, then maybe you should look to what is fast becoming the most popular language for introductory programming on the web... Javascript.

PS: I was not implying that you were asking the group to write a script for you, but that you might have been interpreting the reaction to OTHER PEOPLE who were doing that as a general hostility towards newchums trying to learn.

Not all of them, I'm an impure philanthropist.

It was an analogy, Jesse, presented as an unfortunate attempt at humour. I didn't mean to imply that anyone is ever rude on the Scripting Tips Forum, which is in fact a paragon of civility by comparison with say, the Resident's Answers Forum (Blessem).

I was simply making the point that solutions are very often just as difficult to follow - even as an observer - as the problems themselves. The most casual terminology of scripting can be quite opaque to beginners and, more annoyingly, it stays as such despite the best efforts of the respondents.

We had a few posts from Chosen earlier, who, I think it is fair to say, is fairly well-supported in terms of brain cells and the exercise of suchlike and, for my own part, I have a reasonably good feel for grammar and syntax that suggests a similar facility, but the presentation of LSL clearly lacks something for both of us residents.

I'm not chiding here, I'm whining. Besides regular contributors to the Scripting Tips Forum, I have a number of good friends in-world who have had the benefit of a scripting education of some description and they, quite inadvertently, make me feel like I don't know one end of a pencil from the other when they offer advice: it never ceases to amaze me how the one group takes all that stuff about scripting for granted and hardly bat so much as an eyelid as the rest of us are left feeling like we caught the short bus.

The LSL Wiki ought to be a way of rectifying that disjunction but it isn't. A good editor (with a thorough appreciation of hypertext) would write and arrange it on the assumption that nobody knows nothing.

This is SL, not IBM ferchrissakes.

@Argent:
My apologies for the snark but not everyone wants to have it all worked out for them on a plate. I understand that the odd chancer does just that but I think it's fair to to say that most residents would be just as happy to do it for themselves without having to bother anyone else about it.

I just had a thought here. Maybe using the word wiki is what's getting us into trouble here.

Pros might be thinking of the wiki as the reference guide section; and are saying that they want to keep it clear and concise.

But maybe instead of wiki we should be using the word "LSL Portal."

That portal page can be a big tent -- with a door leading to the clear, concise reference guide, another door leading to tutorials sample scripts -- gee, in fact, just like it does now.

But i'd propose that the two columns -- LSL language reference and LSL categories shouldn't be dominating the main general LSL portal page -- they are advanced material and could be on a linked dedicated advanced page that all us pros could bookmark, and at the top of which we could say "warning newbs enter here at your own risk"

See, and then you genuinely do have the portal intended for "scripters of all levels", while the advanced reference page, isn't.

I think you might have hit the nail on the head there.

Back in 2000, I spent a month poring over a heavy tome from O'Reilly about XHTML. I remember one particularly frustrating weekend trying to get my first patch of CSS to work because, you see, I was using the reference like a cookbook. Unfortunately, the nerds who wrote the book were too busy contriving amusing asides that they neglected to mention my CSS instructions should be enclosed in curly brackets.

You believe that?

Anyways, I eventually found the W3C web site and the CSS specification, which I linked in my second post to this thread, and I never looked back. Beautiful. It was so beautiful that I started using the W3C as a reference for anything to do with the Web.

I even threw the O'Reilly book in the trash, which is why I can't name the nerds who wrote it. I often wonder how much VFM me and the environment would have gotten from £25-worth of toilet paper?

I feel it's better to be accurate and a bit obscure rather than to be inaccurate.

The basics should be carefully covered somewhere, though. I plan to give this some attention.

Actually, a technically accurate syntax description would be more like this:

llSetColor(vectorExpression, integerExpression);

and we'd have to define vectorExpression and integerExpression, and only serious tech-heads would get it.[/QUOTE]

Two different things Argent. There is a certain level of licensed proficiency associated with the term "medical practitioners". Not anyone can just up and claim to be a "medical practitioner". There are legal requirements for doing so. Everyone is acquainted with those requirements and knows what they infer.

It should be obvious that "scripters of all levels" does not have the same connotation. There is no "license" required to be a scripter. There is no formal training. So that phrase, to most readers (apparently not all readers, but the vast majority) would take that to mean beginning scripters as well as advanced.

The argument that the Wiki cannot address all levels of expertise is (again) incorrect. We know it is incorrect because (as already pointed out by several people) there are reference manuals world wide that well-serve their intended purpose for both beginners and experts. Those manuals are not designed the same as the LsL Wiki; the are designed to appeal to a wide variety of audiences. This does require special skills. It requires people who can empathize with others, think outside the restrictions of their own skill level, who can communicate in common English terms, who can write effectively. It's not an easy job and it's not easy to find people who can do it. But there ARE people who can do it... and they've been doing so for decades with positive and useful effect.

Maybe the LsL Wiki will never be such a document. Maybe it will. Because of these discussions Strife is now considering a compromise situation where the current format is retained, while adding an extra line that is more newbie friendly. Why is he considering this? Because Strife empathizes with the needs of others and is able to think outside his experience level (to an extent... even he admits he's not very good at that. LOL). But he's trying... and I think that a positive move in the right direction.

Now this part I can fix you up with immediately if you are running a windows operating system:

http://www.lsleditor.org/

type in the 3 letters def and default will show in a drop down box, click on it and you end up with this:

default
{

}

It even puts the cursor in the correct position for the next entry, shows the tip for the current entry and will auto-indent. If you install the help menu then hitting F1 while on a command will open an enclosed wiki entry for that entry. It is a little out of date now, missing the last couple of new entries, but besides, that is an excellent tool for people learning.

It's not obvious to me, but I'm not going to explain, I have no interest in having further conversation with you.

I think in most pro's minds, the reference section == the wiki.

I wonder if in some places we might instead be talking about the LSL *Portal*, of which the reference section is just that -- a section? What do you think?

Does that help anyone in thinking we might actually be able to agree on some matters? A big tent portal, with sections for various levels of expertise?

I agree. llSetColor is a little too simple a function to make a really good example. Strife and I are hoping soon to test these principles on numerous and more complex statements to see how they hold up.



Very valid questions all. There are several reasons why a clean syntax line is preferred:

* It's shorter. The longer the syntax line, the more confusing to the reader.
* It separates linear concepts from abstract concept.
* It's more exact.
* It's been proved over time to work very well, for both beginner and expert manuals (and combinations of such).

Computers "think" in linear format... one step after another. The human brain doesn't; it processes abstract, ambigious and non-linear thought. That's why it's so difficult for many people to understand the concept of computers in the first place. It's why children catch on to computers faster than adults; they don't have a lifetime of non-linear thinking to unlearn (well, that and they're basically information sponges. LOL).

So in a statement line llSetColor(vector color, integer face);... while those acquainted with that format find it quite easy to understand... to those not acquatined with it, its' quite confusing. Vector (linear) color (abstract) integer (linear) face (abstract). Although consciously they may not be aware of it, their mind is doing flip-flops around these two modes of thinking-- one which requires the left side of the brain (logical) the other of which requires the right side of the brain (abstract). The result... is often confusion.

By separating these concepts into two lines, each line with a specific purpose, we avoid that flip flop and sort them into two distinct, easily-discernable "boxes":

llSetColor(vector,integer); (pure linear)
llSetColor(<red,green,blue>,prim side); (pure abstract)

This tends (over time) to appeal to both newbies and techs alike: the newbies can see two areas of application, which helps them. The techs don't even need the second line, but it's easy enough for them to reference if the term "vector" and "integer" isn't enough to spark their memory.

In our discussions, Strife agrees that might be a concept to look further in to...but he currently prefers the "vector color" format. I can see his point; if he's willing to bend and put in the second line for the benefit of newbs, I'm willing to not gripe about the first line for the benefit of "it's what the techs are already used to". The most important thing is that people actually understand what the "syntax" means. I think with a two-line syntax/concept format (followed by an adequate definition section), that will be the case-- and will cause minimal, minor impact on the currently existing Wiki layout and concept. Strife agrees that SOMETHING needs to be done, so long as he's allowed to present his current format as primary (the big bold letters). That seems to me a reasonable demand. Now it's just a matter of figuring out the best way to do it.

Gawdluvya Jesse Barnett!

Ephraim Kappler seizes Jesse and gives her a big sloppy hug whether she like it or not!

But I already know about the editor - it was one of the first things I found when I began to explore the Scripting Tips Forum. I can't be absolutely sure, but I would hazard that it was a post of yours that led me to it.

Also, I should point out that you commented on my Great Great Great Great Great Great Great Great Uncle Ethen's relatively clean formatting. Ethen, along with my other alts, doesn't post to these forums these days (please Gawd make him rest in peace or pieces even - whatever) in order to save confusion. However, that was entirely down to a general instinct of mine for composition and presentation and I think the point I made at the time, through Ethen, was that:

"I have some experience with Javascript but I don't think I will ever write a script from scratch. I tend towards the Victor Frankenstein method of stitching whatever bits I can find together - and like the man himself, I often have occasion to regret the results."

My problem is that I need a living, breathing, thinking editor - not an application - who will explain the purpose of any aspect of LSL and go so far as to demonstrate the implications of abuse thereof.

One of the advantages of a computer-based instruction system is that it doesn't require separating information into separate "manuals". Let's consider an example:

Syntax: llWhateverStatement(parameters here);
Concept: llWhateverStatement(functional/conceptual thoughts here);
Description: This fuction takes all whatevers and turns them into whenevers.
where...
(parameters fully explained here, in detail)

NEWBIE NOTES (hyperlink, where even more detailed info is presented)

BASIC EXAMPLE 1: (on the same page)
BASIC EXAMPLE 2: (on the same page)
BASIC EXAMPLE 3: (on the same page)

CAVEATS: (same page or hyperlink, depending on how numerous, lengthy and complex the caveats are)

ADVANCED EXAMPLES (hyperlink, where folks can put all the long, convoluted, "hacker tricks" examples they want to put)

SEE ALSO: llWhenever();

As seen from this example... it's totally possible to write a "user manual" and "reference manual" in the same document... which is what we've been trying to get across in this forum all along.

THANK YOU for stating that Ephraim. I think that helped put to rest the prior claim tht I was the only one here who believed this was the case. It very obviously is the case and as you pointed out... many of those well acquainted with the LsL Wiki format simply don't believe it. They need to believe it; it's true. If they choose to not believe it, by insisting the Wiki is exactly as it should be, they do a disservice to the SL community and any non-professional / non-tech who wishes to regularly use the LsL Reference manual.

Actually, allow me to clarify that (I've spoken with Chaz in-world). He's suggesting that people choose one side of the fence or the other. Put another way: either be willing to change and improve the Wiki, or declare it off-limits to beginners and provide them with something else. For the Mission Statement to say that the LsL Wiki is open to "all levels of scripters" but then be obviously designed to be used only by experienced techs (or as you stated earlier, those with the "talent", is to completely fail that mission statement.

So Chaz was simply saying, "change the mission statement, or live up to the mission statement, one of the two".

Can't agree on this one Lear. There's really in my experience, no need for the excessive verbage. And following with ADEQUATE definition is exactly what would take it out of the realm of "tech-heads only" (which btw, many would argue is the current state of the Wiki).

I could not have said it better.



I fully agree. Since it's a computer manual, ALL needs can be addressed by the simple use of links to additional pages (such as "Newbie Notes" and "Advanced Examples".





If he didn't mean this to have any negative connotations... then he frankly needs to get a clue (after continuous such forum postings) as to how his posts come across to the general, non-tech populace. This is a typical "Argent Stonecutter" diminutive statement-- and Ephraim was quite justfied in reacting as he did. The statement was condescending, to say the least. You were not out of line in your response, Ephraim. Tolerating uncivil behavior just encourages more of such. Calling someone on the carpet for bad manners at least makes him aware of such, whether he responds properly or not. Usually not.



The rest of us help new people too (in fact, that's my primary function on SL)... but hopefully in a far less abrasive and far less condescending manner. These things were tiresome with the first such messages, much less as they increased in degree post after post (to the point I and another reader actually had to file abuse reports against Jesse and her cohorts). IMO, to "help" other people... it's beneficial to first view them as peers and have some respect for them... no matter what their current skill level. Hard to help them while insulting their capability and showing open disdain for their opinions.



Which as another user here just IM'd me... I consider a blessing. Feeling is mutual at this point.