Is the scripting wiki helpful to you?

Eren: For over 20 years I've been actually writing manuals and supporting users from secretaries to rocket scientists (I'm in Houston, a lot of my guys have been ex-Nasa), and I gotta say you're missing the point so badly that you can't even see it from where you are.

You're looking for a user's guide. You're looking AT a reference manual. A reference manual that's using the same mechanism to describe syntax that the language LSL is inspired by has used since 1973... at least. Anyone who has the background necessary to learn the language from a reference manual will be familiar with it. Anyone who is trying to learn how to program needs to be looking at something other than a reference manual.

The RPGStats wiki was my personal test site created in July of 2006 to see how easy it would be to port the information from http://lslwiki.net/ to Mediawiki, a modern wiki system. Around August of 2006 lslwiki.net went offline for an extended period of time, I started using google cache to retrieve information and put it into rpgstats as fast as I could. Strife helped me with that and within a couple weeks we had a large portion of the information moved over.

lslwiki.net eventually came back online and RPGStats has stayed since then as an alternative site.

In January of 2007 Rob Linden had a new wiki site using MediaWiki brought online for SecondLife. Several scripters asked if it was OK and started the LSL Portal on that wiki. I was one of them as well as Gigs Taggart, Strife, and several others. The result wasm, after discussions between the scripters and test pages made, The basic layout of a function page you see now. A technical reference, as it should be.

Yes the information is not going to be clear to someone new to programming / scripting. Why? Because they just don't have the background to understand it to begin with.

What the wiki needs is not to screw up a perfectly good function reference. What it needs are "Intro to LSL Programming" articles.

Even then it isn't going to help 100% because you're going to always have the person who has never programmed a day in their life wanting to know how to do things in LSL that are leaps and bounds above their capabilities.

Yes, they also could have left the <> or any symbol totally out of it. But they didn't; they chose to use <> as the visual help aid, so there it is. Yes, the llSetColor statement can use a VECTOR in place of its own syntax. But in bottom line, absolute form, the specific syntax of llSetColor is:

llSetColor(<r,g,b>,face);

Yes, a vector can replace <r,g,b> (or looked at alternately I guess, <r,g,b> can replace the vector... LOL)... but I'm looking at absolute core concept of the llSetColor function. llSetColor(vector, integer); defines the variable-TYPE syntax of the function, but doesn't define what it does. I don't know, at this point the debate likely goes in circles, with one factor feeling it should be one way and another feeling it should be the other way and no way to prove which is best...except..

That under the currently existing format, people are confused. How do I know that? Because if people weren't confused, they wouldn't be COMPLAINING about the LsL Wiki. It is obvious from the comments in this forum that many people do not like the LsL Wiki. I submit that if the work were already a good, valid, useful manual, the vast majority of people would be happy with it. Instead, from myexperience, the vast majority of people throw up their hands in frustration (as I've heard even from long-time, established coders who make a living at such in RL). So obviously, no matter what individual opinion people may have... the current format of the LsL Wiki is not working.

Here's one example, something that has been brought up to Strife before and either ignored or decided against:

As odd as it may seem to established coders, the word "face" is confusing to new coders. I have heard many times "face? what is a face?". Then I explain it's the SIDE of the prime and they say, OHHH the SIDE. Why don't they just say SIDE?

Now while techs may scoff at this... that is valid user feedback. In everyday English, people don't talk about the FACE of a prim. That's techspeak. They talk about the SIDE of a prim.

This is where understanding PEOPLE and how they think comes in. This is where being able to discern the BEST words to use comes into the wiki. Instead of insisting on tech concepts and expecting people to comply to a rigid set of techspeak... when people complain that "face" is confusing... be willing to bend a little and change it to SIDE instead.

From what I've seen, the LsL Wiki folks are unwilling to bend. I haven't seen 'em bend an inch since I've been a member of SL (coming on 4 years now). What I see is ridig adherence to what they believe to be THE way to do it, and newbie be hanged (not an insult... factual observation). It took me banging my head against a wall just to get a concession of NEWBIE NOTES.

Scuse me Lazink, I kind of digress and switch subjects here... but it kind of flowed from one thought into another... the bottom line of how to make the LsL Wiki more comprehensible and user friendly. In all this, I know one thing for sure: if it just continues to be as it is... it will continue to be user-unfriendly. So if people want to improve the Wiki... they need to stop doing what they're doing and start listening to the feedback, then take steps to improve the Wiki. That means changing something somewhere. It doesn't mean insisting on doing what they're already doing (because well... people in general don't like it as it is).

To sum up almost everything that has been said, and it's been repeated here several times. The function layouts are good, they are references, same with most everything else. Better examples, and visuals could be added to help people who are looking at what exactly those functions do and how they work.

A whole new section is being requested, a beginners guide, LSL 101, that is comprehensive, and explains not only LSL, but computer science in general. So the guide needs to teach semantics, USING LSL syntax. This is a difficult and time consuming things for anyone (why good text books costs a lot of money). The downside is that if you get more then a few people working on this, you'll run into style, and how to teach, problems. What do you teach first? Types, events, states, functions... etc. But it can be done.

To sum up, Reference part of the wiki is good, examples could be better, and a true LSL 101 guide should be worked on.

llSetColor(vector,integer)

Umm... what kind of vector? What type of integer?


llSetColor(vector color, integer face);

Oh I see, it's a color vector and the integer is a value for face.

llSetColor(<red,green,blue>,side);

Wait.. what kind of value can red, green or blue be? side?

llSetColor(<fRed,fGreen,fBlue>,iSide);

OK.. I guess those colors are floats and side is an integer... let me try it.


float fRed = 1.0;
float fGreen = 0.0;
float gBlue = 0.0;
integer iSide = 1;

default {
state_entry(){
llSetColor(<fRed,fGreen,fBlue>,iSide);
}
}

Syntax Error? I typed it just like the function reference said.


Honestly... you're proposing an even MORE technical and confusing syntax then what is currently used.

The whole idea of using "vector color" instead of "vector" is so that every time you see that you know exactly the type and format of vector you can use. The more you use the wiki as it is now, the faster you are able to use it as you won't have to read down past that first line as often.

Thraxis, thanks for the history of RPGstats. That was very informative.

What it doesn't answer though, is why RPGstats seems to be laid out so much more productively and is easier to read than the LsL Wiki? (Or maybe that was just my opinion at 1am after a hard day? I dunno).

It's obviously not just a "port" of other information. Someone has done some significant work somewhere, either in additional formatting or re-writing definitions.

Now, I understand and agree with your point that there will always be people confused about LsLWiki because they've never programmed a day in their life. That doesn't explain how it is that seasoned, professional programmers who code as a living come to the LsL Wiki and find the format confusing (and that happens all the time. Anyone who denies that obviously doesn't pay close attention to these forums and the JIRA... or has a knack at selective reading).

When the pros are confused by the layout and format... that means the LsL Wiki just might fall into the category of "poorly designed tech manual"... no matter how much those involved in its writing continue to claim it's just great as it is.

There is a difference Thraxis, between a few non-programmers griping that they can't learn scripting... and numerous hard, seasoned professionals regularly complaining the LsL Wiki does not serve the need. I'm one of those hard, seasoned professionals. So is Chaz and dozens of others. Our professional opinions continue to fall on deaf ears of denial. So I know this: if these forums fail to get that point across, I personally will never again lift a finger to assist the LsL Wiki system. It can go its own way, good riddance, let's see what decent alternatives can be devised.

If someone over there listens and says, "Well, maybe we do need to consider how to improve some things so that the Wiki is more user-friendly"... then these forums will have served a purpose.

Now Chaz said something earlier that I strongly recommend you folks consider (because more and more, I think he's right): if you people intend this to be a pure-TECH manual, designed for established techs and coders only, and NOT as a vechicle for people to learn how to use LsL scripting... then change the mission statement to reflect that fact.

No, it's not.
I don't know why you think that's funny, because that's exactly the case. A vector constant is an instance of a vector.

It takes a color, and a side number. The color is expressed as a vector. That's the core logic.

But I guess you have me killfiled, so you won't see this message either.

Actually, you may be surprised, I agree with you on the integer Face being a bad variable name. Why when I was disagreeing with you about this, I used integer side. I'm not saying the reference variable names are perfect, look at llMoveToTarget.

llMoveToTarget(vector target, float tau);

Againt, vector target is fine, that's your target position, float tau however is rather undescriptive for those that don't know physics. I'm not saying that the reference is bad, just the variable name itself. There is no reason you can't say:

llMoveToTarget(vector target, float time_to_target);

or even better
llMoveToTarget(vector target, float time_to_target_in_seconds);

or even
llMoveToTarget(vector destination_position, float time_to_target_in_seconds);

So yes, I agree with you face in llSetColor is not the best description word and understand why it was used, it's common language for 3d modeling to use face instead of side (I can guess why, but Chosen, or someone more familiar with all the terms could explain why with certainty).

Umm, try float fBlue?
and not gBlue

Which is what Eren does have
<hide from the wrath of Thraxis>

Related: http://jira.secondlife.com/browse/VWR-2318

It doesn't matter what kind of vector or what type of integer. This is a sytnax line, not a definition line.



Since this is a syntax line, the VALUE of red green or blue doesn't apply. Again, that is established in the DEFINITION seciton. By your arguement here Thraxis, I could turn that right around and make the same claim:

llSetColor(vector color, integer face);

Wait... what kind of value can vector color be? face? What range of integers? Or the commonly asked question... "How do I tell which face is which?"

See Thraxis, llSetColor(vector color, integer face); doesn't answer your questions either. Nor should it. It's a syntax line.



No Thraxis you didn't, and I'm frankly surprized. Was that an honest mistake or did you intentionally pull that stunt?

Try changing your definition of float gBlue=0.0; to float fBlue=0.0; and your "sytnax error" disappears and the statement works just peachy fine... exactly like the syntax says it will. Basic coding 101: you must use consistent variable names.



No, I'm proposing you folks start listening to others instead of being so absolutely convinced that you're right and we're wrong.

Remember what I said back there that a prominent trait of techs is "believe they're right even when people around them are telling them they're wrong". Might be time to listen to other people instead of setting your stance and insisting that you're right. People are screaming that the LsL Wiki is confusing, they have been for years... and you folks are just plain ignoring them.




I understand and respect that... IF the person ever gets past the confusing layout and learns how to script in the first place. For the record, in the original forum, I don't think anyone ever suggested you eliminate the "vector color, integer face" section... just that you precede it with a much more viable and understandable syntax line. I think even the most experienced scripters can bend themselves to read one more line for the good of beginning scripters everywhere.

Eren, there are currently 3 "LSL Wikis"

LSLWiki at http://lslwiki.net/ started in or before 2004
RPGStats at http://rpgstats.com/wiki/ a mirror of LSLWiki ported to MediaWiki in August 2006
LSL Portal at http://wiki.secondlife.com/wiki/LSL_Portal started in January 2007

Doesn't surprize me at all. Not to brown-nose, but agree or disagree, I've found your posts here to be both respectful and logically stated. I even glommed a point or two from them... as I have from Ultralite, Chosen, Void and others. That's the great thing about a debate... if we're listening... we usually take away more than we brought to the table. : )

It's extremely useful. Something like this can always be improved.

It's not a tutorial, and shouldn't be. It's a mistake to try to combine reference and tutorial in one document. There used to be a pretty good little tutorial that came with SL, but it disappeared with the shift to web-based documentation.

I just wish it were easier to modify to fix mistakes. The use of templates may be a good thing, but makes it so you have to be a wiki-wizard to make many kinds of modifications (or even to find the text you want to edit).

I've edited a lot of wiki pages, and even been responsible for hosting some, but the use of templates on that site has me baffled. And no, the page that "explains" the use of templates in SL Wiki is no help. It might be to someone who already understood it.

The answer is simple.

For the SL Wiki, they used automatic tools like Categories and Templates to help organize pages, and the result is you get cookie-cutter automated layouts for a number of things rather than hand-crafted ones.

I don't mean this to be a criticism of Categories and Templates. It's just one of the obvious tradeoffs: when you let tools organize things for you, they don't do it the same way you would if you were doing it by hand, with the ability to (and necessity) to hand-code the appearance for each case.

Automation vs. handcrafting. I'm a big advocate of automation; I'm just not blind to its drawbacks.

Because it's not a side, it's a face. How many sides does a sphere have?

It has two faces. It has no sides.

Sorry, but I prefer correct use of English to sloppy use that helps some people understand. The text can use the word "side" as in "such as, which side of a cube ..."

As Einstein said: things should be put as simply as possible, but no simpler.

What drives me nuts is where they use "frequency" when they mean "period" or "interval". GRRR! Unfortunately, that's not just Wiki text; it's baked into the constant name (for particles). This is the problem with letting programmers choose names. Most of them have poor mastery of the langage. But, that's life!

I won't argue with that. It's a logical solution. I'm not sure it's the preferred solution, because I know from experience that a decent tutoral and reference can be worked into one tome. But you made a very valid point Laznik.. the matter of format will be a contention with so many people involved in a WIKI type situation. From what I've seen in these forums, there would be a lot of hard-heads knocking heads on that one... so the liklihood of a one-manual-fits-all (which requires serious coordination, oversight and people-based skills) may not really be feasible.

So your suggestion in the end game might be the best, if not preferred solution. Either that... or the NEWBIE NOTES can be given a lot more prominence... and the techs try to keep their paws out of that section and correct only technical errors, not format and wording. But... that's likely not going to happen either. LOL. So yeah, separate manual for newbs seems the way to go.

But then we get to that catch-22 of techs wanting to write for techs, not wanting to help newbs, and non-techs not having the information required to write such a manual. Somewhere in there, a group of people-savvy, friendly techs are going to need to spearhead such a project. I don't have time for it... my efforts in SL take up almost all my time as it is (plus, I have no desire to do Linden Lab's job for it free of charge). So... WHO and HOW becomes the question.

Scuse me for chuckling... no insult intended... but this reminds me of philosophers. "If a tree falls in a forest..." LOL

A sphere has TWO "sides"... the predominant outside and if it's hollowed, the inside.

A cube has six sides.

A pyramid has 5 sides.

(Suggest looking up "side" in the dictionary for common language usage). ; )

The point being here Lear, is that GENERALLY SPEAKING, the word "face" is confusing to the general public. Techs would understand the meaning of either "side" or "face"... so why are they so insistant on using "face" when time after time people have noted that terminology is confusing-- and that they would prefer the term "side". To me, that's a matter of techs being just plain stubborn and insisting it be "their way".

For the record, I consider "programmers" and "techs" to be pretty much one in the same so yes, programmers do fail to use proper terms in defining abstracts and established procedure. As one person once put it, "Techs forget how to speak English".

I think it's funny Argent, because I have a sense of humor, and I don't see everything in life as a black-and-white, adversarial situation.

Why do you have to read the whole page if you don't want to? The "two lines" you refer to are right at the top. The rest is explanatory info for what those two lines mean, in case you don't know.




How is it unrelated? You've got one section that explains the command, another right below it with some related tips, and a column with some examples in it. It's all related.

That is unless you're counting the text of the examples. In that case, yes, you're right. The night life of Barcelona is unrelated to making text bold and/or italic. Somehow I don't think that's what you meant, though.

In any case, whether or not you agree with everything the author has to say in this particular book is not what's at issue. What I was exampling was the structure. The what-why-how setup is very, very effective.




If it's so useless as a reference, then how come I grab it every time I need to look something up?

If I'm working in HTML, and there's a command I don't remember, I simply look it up in the plain-English table of contents, flip to the page, and the command is right there. Is that not precisely what we all do with the present wiki every single day? It's the same exact thing. The only difference is that there also happens to be plain-English explanatory information alongside the command listings.

As for the "page after page" stuff, that's simply not true with this particular book. Every single HTML command in existence has a page exactly like that bold/italic page in the example image. It's one page per command, which is again, exactly like the LSL wiki.

And as for the amount of space, as you well pointed out, we're talking about a website here, not a book. So who cares how much space is taken up? Whether a page is a thousand paragraphs or just one paragraph, it's still just one page. It still takes only one click to get to it, no matter how much content is on it. The only thing that changes is how far one must scroll in order to read the whole page, if indeed one does want to read the whole thing, which clearly you wouldn't, since all you'd be concerned with would be the command listing itself, which would be right at the top. So what would possibly change for your own personal usage of the wiki?

Here's an analogy I often use for this sort of thing. I'll never forget the first time I went swimming in the ocean. I don't remember how hold I was, but it was in the single digits, and I was scared out of my mind. "It's sooooo deep!" I exclaimed to the instructor. With a pleasant chuckle and a smile, he replied, "What do you care? All you're going to use is the top two feet."

Well, here's my pleasant chuckle and smile at you, for this case. What do you care if a page contains information you're not going to read, as long as the information you want is right at the top? How could it possibly change your experience in any way if there is or isn't a separate section on each page for plain-English explanation if you're not going to read that section?

Forgive me for saying this, Argent, but you're starting to sound awfully territorial about this. The fact is there are people struggling needlessly because a much needed teaching tool is absent. The fact that you personally don't need it to be present doesn't negate the fact that others do. Different people have different learning styles. Any reference material worth its salt needs to recognize that, and offer a multitude of pathways to the same information. To do otherwise is to operate in denial of truth.

One more story, and then I'll wrap this up. My current career is actually my second. My first was running a sales and marketing business, which had a gigantic college internship program. We prided ourselves on offering some of THE best sales and communications training in the world. I taught regular seminars on subjects such as psychology of sales, presentation skills, effectiveness in communication, motivational speaking, etc. For attending these seminars, and applying what they learned from them to doing sales and customer service for for my company, my students were able to earn (in addition to a nice paycheck) anywhere from 4 to 16 credits at schools ranging from local community colleges to major ivy league universities. So I'm not without a degree of expertise on the conveyance of information to the human mind.

One of the things I used to teach in my psychology of sales courses was the following concept. Sales and education are the same thing, as the purpose of both is to present information in such a manner that the intended recipient can most readily absorb it. In order to educate (or sell) effectively, the teacher (or sales person) must recognize and accept that there exist several different methods by which people learn, and they're most often tied to various senses (sight, smell, taste, hearing, touch, and kinesthetics). Some people are sight-based learners, and respond best to visual demonstration. Others are hearing-based learners, and respond best to vivid verbal description. Still others are more kinesthetic, and respond best to things like body language, tone of voice, etc.

As a teacher (or a sales person), how do you know which student (or which customer) is which type of learner? How do you know which senses to hit on in your presentation? The answer is you don't. So you need to hit on all of them all the time.

If you show a picture, for a picture, don't just display it. Also describe it. What's happening in it? What does it look like? How do the things in it feel and smell? What do they sound like? You have to cover it all every time, or you'll end up leaving people out.

To be most effective, the wiki needs to do the exact same thing. It needs to hit on as many different learning styles as possible. While some people can just look at a command and know what to do with it, not everyone can. If someone can't, it's not a failing on their part in any way. It's simply a difference. The failing is on the part of the author/teacher who did not take into account the human factor in the presentation. There must be multiple pathways to the same information, always.

At present the wiki is only useful for a small subset of people, those whose learning style happens to match its current (limited) presentation style. To be useful to the public at large, it must be amended to include information that can be absorbed by a multitude of differently abled learners. That's not necessarily hard to do. It just takes a deliberate effort.

It can't just be a list of commands. It needs also to be descriptive. Why is the command structured the way it is? How is it used most commonly in conjunction with other commands? What does it look like in a script? Etc., etc., etc. It's all got to be there, on each and every page, or there will always be a significant percentage of people who simply can't learn from it. And again, that's not a failing on the part of the readers. It's all on the authors to accept the simple truth that human beings tick the way they tick, and that's that.



Well of course the Web pages don't need to look like book pages. That wasn't the point. Again, what I was trying to show was the kind of information that should be at your finger tips at all times.

In any case, I don't at all believe that a reference manual and user guide need to be two different things. As you said, it's hypertext. The formatting is dynamic. Display can be fluidly restructurable by user preference. That is, after all, what Web pages are for, is it not? Otherwise, we'd still be using paper for everything.

Thanks. Yup, was aware of 2 of them and had them bookmarked. For some reason I hadn't heard of RPGstats before... and wound up liking it best of the three. Wish it was more up to date.

Neither of you are "helping" anything by dropping down to personal comments (or in Jesse's case, outright intentional insults). It's pointless and negative and just diverts attention away from the main thread.

I'm not "mad" at all Sindy. I make a point of keeping "emo" out of things. Like many, I'm a little frustrated at the unbending nature of the current Wiki folks, but that goes without saying. But you and Jesse both have diverted from "discussion" to personal attacks since just about post one... which diverts attention from the theme and purpose of the thread. If you want to serve that purpose, stop impuning my motives and stick to the subject.

Argent Argent Argent...

Coders are known for hacking and abusing and distorting code. They have a history of it. The above example is a totally valid (although possibly useless) way of using the llSetColor function. It has nothing to do with the basic syntax or logic of that function... nor does it (imo) have any impact or bearing on how a proper reference manual should be written or how the core syntax of that function should be presented.

It's ok - that's what they all say, hon. Best of luck to you.

You coulda fooled me on both, dude.

Heck, you did.