Is the scripting wiki helpful to you?

Argent, if you really thought that I'd bother to debate with such statement, you were mistaken. I do not argue just for the sake of arguing, nor do I take such statements as valid application of logic in real life, realistic situations. You're going to have to do better than that for me to take you seriously. Honestly guy...

This is real-life realistic situations. This is over 30 years of experience as a programmer and technical writer. This is 20 years of experience supporting real people in real life realistic situations. This is almost 4 years of helping real people in second life realistic situations. If you're not willing to listen, I can't force you, but you're the one who's the poorer for it.

I can make the same claims Argent and add a few years to your experience. Yet I strongly disagree with your opinions. Guess I must be right because of my greater experience? Experience counts for something Argent; it doesn't count for everything, nor does it make one all-knowing or infallible. It improves your odds, and that's about it. Personal experience counts for one thing: personal experience. It doesn't set the laws of of the universe... nor do others have to accept and adopt your personal experience. We have plenty of our own to deal with, thank you.


You know, I've managed to live my entire life without the wisdom of Argent Stonecutter guiding my path... and I somewhat suspect I can continue to do so and by no means be any "poorer" for it. LOL. I mean, seriously guy...

WOW. Erin you are insane! Go ahead and AR this but it is here for everyone to see. There really is not anyone left that you have not insulted. You will not being seeing anymore of my posts directed at you because you are on my ignore list now. I might suggest everyone do the same. Shunned, outcast, invisible. Keep on posting all you want but I do not think there will be very many to listen anymore.

I've never seen an attempt to do this that didn't fail at both.

The same BOOK can do both, but any good tutorial book has a reference section.

A website has a lot more tools to do the job, but it's still important to provide reference material whose primary intent is not to teach the basics.

I don't know where this came from, but I hope it's part of an example and not a recommendation for the introduction of the function.

After reading through this thread, i can't help but ask this question:

Suppose you have a function, which needs several parameters of the same type. What would be the best alternative for a syntax/definition ?

1.) llTriggerSoundLimited( string, float, vector , vector );
2.) llTriggerSoundLimited( ssound, fvolume, vtop_north_east , vbottom_south_west );
3.) llTriggerSoundLimited( string sound, float volume, vector top_north_east, vector bottom_south_west );

i personally prefer the option #3.

And one more remark fr0m a casual LSL programmer with limitted skills:

I learn best by searching for code snippets and trim them to my desire.
So this is my typical workflow:

- cut/paste the definition line (or example code) to my script.
- reuse the variable declarations as in the function definition:

string sound;
float volume;
vector top_north_east;
vector bottom_south_west ;

- i cut/paste the function definition and remove the type declarations:

llTriggerSoundLimited( sound, volume, top_north_east, bottom_south_west );

===

So if i had a whish free, i would like to see the functions defined like this:

The "definition" section shall be followed by :

* What the function does
* Where to take care
* example snippets
* further reading
* Link to at least one fully working script with meaningfull content

So naturally the sl-wiki is ok in most of the time for my needs. Sometimes it could be more explanatory though. When my questions are not answered in the sl-wiki, i switch to the lslwiki.

And what would really make sense to me:
add a template mechanism to the inworld LSL editor, so that i can type in a function (or select fr0m the function pullddown menu) and get the whole calling line automatically pasted into my script with standard variablenames...

The quoted part above is pretty much supporting my personal workflow,
so please just take it as an idea, and don't bother if it is not adequate.
These are just my 2 cents in the hope for a constructive contribution.

I agree with you about option #3, Gaia.

Furthermore, there's a reason that the form used by the wiki is shared by the vast majority of modern strongly-typed languages (including Pascal derivatives as well as C derivatives). The main reason is just what you pointed out. Assuming you know the basics of the language (i.e., how to read or write a function), you find the type and name of each parameter. The names of the parameters are very important for the description part! Imagine what it would be like to try to document a function like this:

llDiscombobulate(integer, float)

using "the first argument" and "the second argument" rather than

llDiscombobulate(integer repetitions, float amount)

using "repetitions" and "amount".

It would not aid the readability of the text for either novice or expert.

It's even worse to try to use an example as the prototype. The problem with examples is they omit alternative possiblities, and it's never clear which aspects of the example are normative and which are merely illustrative.


The following:

integer repetitions;
float amount;
llDiscombobulate(repetitions, amount)

is quite a bit better than my first example above. It's not as concise, and I wouldn't prefer it, but perhaps Eren would. (If so, it might be a good idea to say so.) We used to do things that way in C, before typed function definitions were part of the language (before many of you were born). I'm glad we got out of the habit, but perhaps this would be less daunting to someone who did not know the basics.

As I mentioned above, we need a good "getting started" tutorial, introducing the major concepts for newbies to coding. There was one that wasn't too bad, but it's gone.

OK, I'm starting to see what you mean now. Whereas I'm approaching it more from a "How does one do ______ task?" perspective, you're noting that that's not the same thing as "How is ______ command used?". I'm starting to see how having a reference section separate from the guide section would be beneficial. Thanks for taking the time to explain.




OK, so we're not actually in disagreement on the plain language explanations. Good.
And yes, I see now that the book's structure of organization by task is very different from the wiki's structure of organization by command. Sorry I didn't understand either point until just now. Again, thanks for explaining further.




I get it now. Thanks to you as well.


What I'm now envisioning is user guide, organized by task, in which each command mentioned would have a link to the command's reference page. Likewise, each command's reference page would have an index of links to all the pages in the guide in which the command appears. This would basically incorporate all the good ideas that have been proposed in this thread, in a very logical, and easily cross-referenceable manner. I see this as a much better and more evolved solution than what I'd originally had in mind. Thoughts?

Happy to see we're making progress!

The place to start is to plant an LSL_Tutorial page in the wiki and start working.

Does anyone have the tutorial that used to come as part of the SL client, delivered as web pages? This tutorial had a number of specific shortcomings, but overall did a great job of introducing the major concepts with a minimum of fuss (which is not an easy thing to do). It would be a great starting point.

IIRC, it started with a "hello world" program, then introduced the basic types, then functions, and finally states. Even as an experienced programmer, I found it helpful to get the basic idea of LSL.

Listen up Eren:

1. create an object
2. go to the object contents
3. click the New Script button
4. type llSetColor
5. hover your mouse over the word

what does it say?

don't mess with our wiki because you are so full of ideas about the way things should be that you are completely disregarding the way things are.

If you really think it is so much more transparent to express the syntax in the ways you suggest then talk to LL about changing the way they express the syntax.

llSetColor() takes a vector and a float. It doesn't take '<', three floats, '>' a comma and a fourth float. You are plain wrong and your whole approach to updating the wiki is wrong. This is a prime example of why, and an excellent demonstration of how you sap everyone's energy and attention from the task at hand by distracting them down pointless avenues, all because of your 'professional technical documentation' hubris.

Your approach doesn't lead anyone into an understanding of vectors and if they are going to code in LSL there will come a point that they need to understand that they are a variable type, no matter how much you try to disguise it. Vectors may be defined as three floats but they are declared, passed and manipulated as a discrete type. They are one of the things that make learning LSL seem scary because they are not likely to be familiar to most people, whether or not they have used other programming languages. Rather than attempt to avoid them or to disturb the concise and accurate expression of syntax in the wiki they need to be explained and understood somewhere else.

This idea that everything should be explained on every page is just plain stupid and detracts from the wiki's usefulness as a reference document. There are many new terms and concepts when one comes to LSL and they need to be learned but obfuscating the function references is not the way to teach them.

The why is quite simple: which 'side' of a sphere is one colouring? Ok, inside or outside, I guess, but when it comes to complex meshes (which we hope will be introduced to SL soon) then side becomes less helpful and face becomes completely apposite.

Precisely because face is widely used in the 3-D modelling world it is good that LSL uses that term rather than any other.

I can't stand reading all this pointless jibber jabber but I just wanted to say that adding a section called Newbie Notes to llSetColor and then restating everything from the function definition in almost exactly the same words is a total waste of time.

So we change it to 'side' just so they can ask you "How do I tell which side is which?"?



Sure we do, troll. Maybe it might be time for you to listen to all the people who are screaming that you are missing the point on how the wiki is used as a reference.

If you want to write a mickey mouse manual then go ahead but don't mess with what works for the rest of us. Once those who use your manual to learn LSL have got their heads around the concepts they will drop yours like a turd and come to where they can find concise and convenient information. The only people I have heard screaming are you and Chaz. If you have a load of people screaming about the wiki why not direct them first to some of the tutorials that are linked from it and tell them they need to learn some of the concepts before they can hope to be comfortable with it.

I found a publishing similar to the lsl_guide here:

http://oz.slinked.net/history/lsl2_reference.htm It may be an older version, or a rewrite.

I also found an interesting mailing thread about lsl_guide.html here:

https://lists.secondlife.com/pipermail/secondlifescripters/2008-October/003728.html

The thread says, that the file has been removed. But this is not true. I found it right in the distribution folder of my SL client (i use the release candidate). So it should be available to everybody. In the thread they also talk about the official wiki is the better source of documentation by now ( i do not comment this, just report it!)

There weren't any such in the building and scripting forums until you butted in Eren. Take a look at the thousands of posts from those you are calling trolls and you will see their thousands of postings (as opposed to your 64, most of which are in these two threads) are intelligent, helpful and friendly. Your passive-aggressive style of writing has managed to rile some of the most respected people in this forum. Take a look and see. When Sindy says you are transparent it is because to others it is completely obvious that you are throwing insults out and then saying "I don't mean to insult", behaving like a troll and then accusing those who react of being trolls, insisting on your own opinions and then calling everyone else opinionated, ...

This thread shouldn't even exist. It was started by your friend Chaz in order to garner support for his case that people don't like the current wiki because he knew he was more likely to find such support in the building forum than the scripting forum, where he expressed that opinion. Then he called you in to troll your 'professional' opinion that the wiki is not good technical documentation. You are right, people should be able to offer their opinions on the state of the wiki rather than make it personal but the fact is that your 'opinions' are not about the wiki, they are about your personal view of techs and programmers, their competence in expressing themselves, interpersonal skills, and ability at documenting their work. Just because you generalise rather than direct it at individuals doesn't make it any less so. In fact it guarantees that you will offend more people than if you had ascended to personal attacks (and, yes, I do mean ascended; your frequent side-swipes at techs are dishonest and disingenuous). You do all that you accuse others of; whether is is failing to listen, trolling, insulting, ... and even worse you do it dishonestly.

Let's get on with the two constructive things we could be doing: improving the utility of the function reference in the wiki and providing more educative materials for those who don't seem to have taken advantage of those that already exist.

http://wiki.secondlife.com/wiki/Help:Getting_started_with_LSL
Linked from the wiki, along with a list of links to other tutorials, which, it seems, none of those throwing up their arms at the function reference have bothered to read.

Do you know if the link you mention is a derivate from the lsl_guide.html or is it a complete rewrite ? I could not see that it is the same content, only the same topic

Anyways the information i have read about the lsl_guide.html makes me think, that it is outdated and the wiki content is the newer and more correct. Would you agree on this ?

I've been thinking about this. The tutorial that Prajna linked to, along with a couple of others which I think were links in the same section of lslwiki, were how I initially learned. Revising and updating these as Lear etc. are discussing, would be most excellent, and are within the grasp of what we could actually achieve. I DON'T see us creating a really good user guide, like that which Chosen learned from, and that Argent (quite rightly) resists turning the wiki into..

One idea: Folks have suggested something like "newbie notes" be added to the template for each command. I don't think this is a good idea. However, would it be useful to add a set of links immediately after the command definition, right at top, called "Usage Notes"? I'm thinking this could contain links to articles such as: "Using llRotateTexture vs. llSetTextureAnim" -- articles that would contain usage notes that would help a user decide WHICH command to use, and also caution them about performance impacts. A few of the existing article links from the "See Also" section would move into this category.

Good idea? bad idea?
.

Don't know Gaia. I wasn't around to see the original or overlooked it when learning LSL. I simply dived into the wiki (and lslwiki, which I like because on rare occasions the comments add more explanation to the main reference articles).

In any case it seems we need to address the difficulty of newcomers to find helpful introductory documentation.

We shouldn't be calling the "prototype" the "syntax". Eren is correct that it's not a syntax line. (Nor are his suggestions; a true syntax description would be far less legible, as those of us who've worked with formal syntax description languages all know.)

It's a prototype, and that's what we should be calling it. It serves an excellent purpose, and newbies to programming would do well to learn that first.

I disagree. More people will understand us if we call it "syntax", even if the term is less completely correct.

Keep in mind that K&R did not have many non-programmers in its audience.

As Argent himself pointed out, further back in this thread, we are dealing with hypertext here, in which case I see no reason why idiot notes cannot be supplied via links within the text.

"Listen up?" "YOUR Wiki?"

LOL. You know, if you disagree with my definition of "techs" several pages ago and feel I was insulting (I wasn't)... then the general idea is to not turn right around and prove me right.

LOL. Prajna, despite your insistance that you're just plain right and that I'm an idiot... Strife and I are discussing at this time on another forum that the thoughts I've presented here very likely have merit after all and need to be incorporated into the Wiki in addition to the current formats. I fully agree with him that the original format should stay. He agrees that an additional CONTEXT and expanded definition area is likely well in order.

That's how these forums work Prajna. They consist of people with differing ideas and opinions coming to an agreement and upgrading current things for the good of the greater number of people... not just a handful of techs who think their opinion is law of the universe. It means being able to bend and realize that we don't know everything, our opinions are not absolute constants, and someone else just might have a valid thought-- if we'd simply take time to stop and listen to what they're saying.

If you believe that constantly and repeatedly attacking me and my viewpoints is the way to conduct yourself on these forums... let's see what the moderators have to say. I'm amazed that three people on this forum seem to be totally unaware of how to behave in public... but like I said, tech attitude and hidden-behind-the-keyboard bravado. Strikes me that if you were so correct in what you say... you wouldn't have to stoop to personally attacking others to prove your point.

Lear here makes a valid point, but then so does Nika. It's best to call a line by the correct name, but then again, would "prototype" be confusing to most users? I think it would. Prototype of what?

Even if the statement does not apply the rules of the term "syntax" (which it currently doesn't) it will still likely be recognized by that as most people. The suggestion I made to Strife that he seems to be comfortable with:

Syntax: llSetColor(vector color, integer face);
Concept: llSetColor(<red,green,blue>,prim side);

Now technically, neither one of those are true, actual SYTNAX lines. A true, bonafide syntax line would be:

llSetColor(vector,integer);

... and yes, I think it's a shame that we're not using true syntax on the syntax line. But all communication is involved in compromise, and I think bending a bit on both sides will at least wind up with a Wiki that is understandable... which is the real goal.