Is the scripting wiki helpful to you?

The wiki(s) are online reference guides, and although they could use improvement they are structurally well-suited to that purpose (at least, if they ever set up a search tool that works for the official portal. As it is, I tend to use lslwiki and the portal in tandem.).

They're not suited for teaching new programmers how to code or for folks who are not familiar with the concepts of event-driven languages. It would be great to have better tutorials available, for folks who need something more -- particularly as LSL is really quite simple and powerful. I haven't read all the posts, but so far haven't seen mention of two available teaching resources:

> In-world scripting classes
> The book: http://www.amazon.com/Scripting-Your-World-Official-Second/dp/0470339837/ref=sr_1_1?ie=UTF8&s=books&qid=1241135714&sr=1-1

Are either of these helpful for new scripters?
.

You conveniently overlook that you created this poll in a forum where it was aimed at builders rather than scripters and fail to acknowledge that 70% of the options you give are to canvas votes against the current format.

I hold with my comment, which was made in the context of your posts on the scripting forum, where you made clear that you were in favour of changing the format of the wiki to better suit inexperienced scripters. You can hardly claim to be unbiased in this. What is the track you are on? Why can't we have two separate resources, each suited to their task? Instead of trying to subvert the wiki, which even your biased poll shows to be useful in its current format, you could put energy into establishing something that would be considerably more accessible to beginners.

And nothing prevents there being a section of the wiki dedicated to introducing newcomers to LSL. Indeed it would seem the mandate requires there be something to help them. Messing with the reference aspect in order to accommodate newbies is not helpful for competent scripters. So why not fully comply with the mandate and improve things for both newbies and experienced scripters. Shuffle simple explanations off to a newbie section, providing them with a genuinely useful, friendly introduction and freeing the reference section to be concise and specific?

@Prajna I'm not going to engage in flames or attacks. They aren't productive. We all know how to rile each other up very well. So I'm going to disregard your first post directed at me, and I'll address this one.



That doesn't sound like a bad idea. Let's hear what others think. There is though I suppose the issue of having to find person power over the years to update a topic in two areas -- multiplied by the 18 or so languages that the wiki seems to promise at the top that it's available in. Again, let's hear what others think. Cheers!

Actually, I just thought of another alternative: one simply deletes this part of the mandate. "It is intended to help scripters of all skill levels.", and states instead that the audience for the wiki is people who already know how to script.

Well said Chosen.

You know, I'm going to get off-topic just a LITTLE here and discuss some facts that are well known in the corporate industry... why people often have problem with techs. (And I might point out that Chosen Few is one of the few exceptions to the stuff stated below. My past chats with Chosen have been quite friendly and beneficial).

Now mind you, I've worked in the tech industry all my life. Most folks would consider me a "tech". But I'm one of the rare techs that also knows how non-tech people think, because I trained in other areas before getting into computers, and worked in people-focused corporate industry all my life and HAD to learn such things. But I do know tech-mind and how techs work and think. I've been around them and lived and breathed with them all my life.

THIS DEFINITION DOES NOT COVER ALL TECHS so if you're a tech, don't get your fur in a twist. But in human resource departments, among corporate mangement heads, in headhunting firms, there are a few things that are generally recognized about the "hard tech" personality:

Very, very by-the-book... resistant to change... brilliant but highly opinionated... disdainful of other people who are less-tech oriented... tends to be anti-social... tends to have a small and close-knit circle of friends (if any-- usually other techs or those in the same field)... tend to insist that they're right even when others around them are telling them they're wrong... don't relate to general business and the public well... have difficulty relating in common, everyday-use language... tend to be offensive in mannerism and communcations to others... often have difficulty getting ideas across to others... would rather chat by email than face to face... arrogant (to varying degrees)... are uncaring of others and unempathetic to the needs of others... self-centered and self-focused... tend to believe that if it works for them it should work for everyone... tend to claim something "can't be done" due to failure to think it through... tend to believe anyone who can't understand the same things they understand is a moron...

...well, I think the idea comes across. Most people are aware that techs are a different breed.

These aren't insults and slams upon techs. This is a typical personality-type that comes with the trade. They're into bits and bytes and code and circuits and that very mindset makes it difficult for them to relate to PEOPLE... much as outgoing salesmen generally do not relate very well to computers.

Why am I bringing this up? Because these things are why, in the corporate field, there is are two well known rules of thumb:

Never put a tech in charge of people.
Never have a tech write a manual.

Now, when we come to the LsL Wiki... it's pretty predictable that the techs who are comfortable with it and use it on a daily basis might want it to stay just the way it is. Resistant to change and lack of empathy for the needs of others.

But it's also understandable that non-techs feel just exactly the opposite. And as shown above, the techs are going to consider the non-techs "kindergarteners" and look down their nose at such ones because well, everyone should be as smart and informed and educated as the tech.

This doesn't mean ALL techs are like this. Obviously there are a number of techs who are friendly and open minded and willing to change. But IN GENERAL, the hard-techs mindset deals better with circuits than with people. Thus confusing reference manuals that only techs can understand.

So when it comes to something like "what to do with the LsL Wiki"... in general it has to be realized that heavy techs are going to have a tendency to resist any change, and disdain anyone who recommends such change. That doesn't mean the techs are right. It doesn't mean the non-techs are wrong. It doesn't mean the change isn't needed. It means they're not going to be happy about it... even if it's necessary.

So... maybe as some folks suggested above, the time has come to write a NEW manual, one not written BY techs and one the doesn't cater specifically TO techs (for that is for a certainty the state of the current LsL Wiki). Maybe what is really needed, is to start a separate and new project, a REFERENCE manual rather than a TECH manual, that's meant for the other 99.9% of the people who aren't techs. Maybe... it's time for the rest of us to stop trying to support and upgrade the Wiki (since that obviously hasn't worked for years now) and move on to a more realistic, new project... a totally new guide designed to benefit the SL populace in general.

Or as Chosen said... start making use of the NEWBIE NOTES and add some better DESCRIPTIONS... and the techs keep their tech mits out of that cookie jar.

I suspect a major problem with the idea of getting info from books is that books aren't free.

One way to maybe find some different than the more common resources is to do a Google advanced search for Linden Scripting Language, filetype pdf.

Here's on of the links that appears in that search: http://www.distance.mun.ca/media/files/secondlife/Second%20Life%20Tutorial%2004%20-%20Scripting.pdf .

There used to be a section in the old lslwiki.net wiki that I felt was very well written and good for beginners. It was gutted by the people that didn't need a continuous readable passage and only needed brief references with lots of links instead of continuous, readable text. I'll wager this might happen to any good, thorough, readable beginners section - for example, an idea in a beginners guide might be repeated; the inconsiderate knowledgeable user deletes all the repetiton because it's wasting his time (and quite likely to conserve bytes on the wiki server). It's a problem, beginners' can't write the beginner's guide because they don't know the material, the expert's don't need a beginner's guide, their return on time invested is greater when they improve the wiki for themselves and other experts.

Actually, I learned how to script from the wiki. However, I had good, though rusty, experience in programming, including one or two event-driven languages. Remember, the wiki currently includes a few tutorials as well.

fwiw, I know someone who has read the scripting book I cited above, and it seems to be helping him get a leg up, if there are any reading this thread who'd appreciate a better-structured learning experience, they might want to take a look.
.

Well-stated. That is indeed the proverbial Catch-22. Techs write for techs... and no one else.

Talk about slanted poll, 7 out of 10 answers are negative responses. But it's nice to see that majority do like the wiki. Maybe a simple 1 - 10 rating would give better results.

Not just resistance to change. Resistance to certain kinds of change.

Part of my job is writing manuals. Part of my job is REwriting manuals that have been massaged by non-techs into something the "reads well". Unfortunately, "reads well" often means "is just plain wrong". You don't fix a technically correct document by getting someone who is a "non-tech" to re-write it. You fix it by finding a tech who can write, OR by PAYING a tech to fix it back again after it's been screwed up.

If you're not going to pay for that, then leave it alone. Write a separate user's guide. Not a "newbies notes", a real user's guide. But you'll still need a correct no-matter-how-prickly reference manual full of jargon as well.

I fail to see how this ... I can only call it a rant ... is relevant to the evolution of the LSL wikis. I'm sorry for the obvious bruises you have suffered from those in the technology industry who have caused you pain.

Technologists share character traits with other disciplines that require a lot of expertise, a lot of focus, and a lot of interaction with data instead of humans. Certain types of medicine, many economists, mathematicians and other scientists ... the list goes on. So, let's not get our fur all in a bunch about evil technologists

Any documentation which has a multiplicity of audiences (in this case, both professional programmers and novices) will only succeed if it has sections that address those very different audiences. Personally, I prefer those to be completely different pieces of documentation, because I think that frees the writer to use the media best suited to the audience. But, as SuezanneC (and probably others; haven't read some of the thread) suggests, a good newbie section to the LSL wiki would be a great addition.

I really think there needn't be a debate about technologist's vs. nontechnologists in play here, Eren. The fact that a reference document is unsuited to teaching is pretty obvious.

I just question whether it is realistic to expect residents to produce really good learning tools for newcomers to programming.
.

Maybe some Wikipedia links would help.

Eg, http://en.wikipedia.org/wiki/Finite_state_machine

It's not dumbing it down to add a few paragraphs to each page, in a section anyone could easily skip over if they're not interested in reading the plain language. In fact, I'd argue just the opposite. It would actually be smartening it up, in that it would make for far more robust and descriptive communication of the information it contains.

If the presence of plain language would really bother you, though, then how about putting a simple filter in place to block the plain language section of each page from displaying, for anyone who prefers not to see it? Seems to me, it wouldn't be very hard to set that up at all.




Ever see an instruction manual written in more than on language, with, say, the top half of each page is English and the bottom half is Spanish or something? Did it take a lot of effort for you to skip the Spanish part and just read the English? Undoubtedly, the answer is no, it did not take any effort at all. Well, you could just as easily skip the proposed plain language section of each page on the wiki, and only read the tech-language section, if that's what you prefer to do. There's absolutely nothing to lose.

But again, if for any reason it really WOULD tale work for anyone to skip reading the plain language section, it could easily be switched off or collapsed at the touch of an on-screen button.



Understood. That's why I said BOTH halves are crucial. We need an introductory manual AND plain language on every page. The whole idea would be for the individual wiki pages to follow up on what would be taught in the intro. People often learn best through repetitive observation. If the same kind of language appears in multiple places, there's more opportunity to absorb the information.

And one more time, I'll stress, none of this need interfere in any way with the presentation of the material that's already there. All of this would be supplemental content.




It can't be all things to all people, sure. But it certainly can be made useful for the kind of newbie audience we've been discussing here, without sacrificing a single thing it currently has going. If you can't see that, I'll take the blame for not (yet) explaining it well enough.

Here's a scanned page from that HTML book I mentioned, which might give you a better idea of what I mean:



See how everything is in its own neat little section? If all you're looking for is the command syntax, your eye goes straight to it. But if you also want to read more in-depth explanation, examine examples, grab some useful tips, it's all right there for you. The material is as easily useful as a straight lookup & reference solution as it is as a full blown explanatory teaching tool. Whichever approach you want to take, it works.

And again, if you'd rather not see the extra stuff, just collapse or hide the sections you believe you won't use. As I said, there's absolutely nothing to lose with this approach, and potentially so much to gain.




Right. That's why it's so important that likely unfamiliar concepts be explained right on the page(s) where they appear. That book page I scanned doesn't make complete sense all on its own, either, unless one has read the introductory chapter. But it does make a whole lot more immediate sense on its own than would just a listing of commands, and if one IS reading it as a followup to the intro, one can't help but learn the material.




Now we seem to be speaking the same language. That's exactly what I was proposing. I suspect our approaches to the "improve the utility" part might differ a bit, though.

Those are insults, how is it your mind is twisting it around in such a manner that you have deceived yourself into thinking it is anything else? It is a flame, you keep flinging out insults and then act shocked that others do not react well. You have repeatedly professed the admirable job that Strife has done in the wiki and in the next paragraph of the post insulted the hell out of him in the other thread and then try to act innocent. Your post was insulting, be proud of it and don't try to play it down or try to hide behind a couple of nice words in an otherwise vile post.

You keep stating that you know how the information needs to be presented to everyone and yet everyone here needs to look at what he submitted as edits. So lets give you an opportunity here to present your ideas. Post a set of links to the discussion pages with the edits that you had proposed and were subsequently shot down. Let everyone here be the judge. They will laugh just as they laughed at your really absurd take on this:

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

This is how he thinks it should be in the wiki. Everyone care to raise their hands that agrees with this?

Just reposting Strife's questions in case they got buried:

Now as to the rest of the thread. Chosen you summed it all up nicely with this:



This is the point and the problem. I spend a fair amount of time in Mexico. I have a Spanish Dictionary and know quite a few words and can order a meal or a taxi etc, but my Spanish sucks. A Spanish Dictionary does not teach you how to speak Spanish, it does not teach you how to string the words together to create conversation. It only defines words and that is it's job. For each word defined it may even show you how to use it in a sentence but it does not show you how to create a paragraph with each or teach you to speak Spanish. If I ever really decide to learn Spanish then I will take classes.

This is exactly what we face when we are new and learning LSL. It was the first scripting language I learned. The wiki's are invaluable resources and they do the job they are supposed to do well. They define each entry. To learn LSL thou you have to make more of an effort and there are multiple resources out there to help with this. Scripting Classes are offered all the time, a plethora of examples are scattered around. The Scripting Tips forums is irreplaceable. Books in print and I saw an ebook around that was free at one point.

Yes the wiki's can be improved but no one should ever expect to learn to write code from it no more then I should expect that Spanish Dictionary to teach me Spanish. But both that Dictionary and the wiki's do what they are supposed to do pretty well.

That is the other thread though and was not the purpose of this thread.

Jesse, I'll say this again: I'm not going to get drawn into your rant posts and trolling. You want to discuss issues, we'll discuss issues. You want to flame, I'm not interested... nor am I interested in your personal opinion of what is flaming and what isn't. You were negative and insulting from your very first post, have continued to be so... and I'm not going to drop to such levels by attacking you in return. So rant and troll all you want... you're not doing your position any good; I certainly don't consider such posts to hold validity.

You can scoff and "laugh" at the above format all you like. You can call it "absurd" all you like and be as insulting as you like. The above is an industry-standard format that has been used in reference manuals world-wide for decades-- and was presented only as a valid ALTERNATIVE... not as my preferred method of presentation. The fact that you comment disdainfully regarding such and make fun of what is a widely-used standard does no more than prove the points I made in the post about common tech attitudes, self-focus and contempt for the opinions and preferences of others.

Actually that's a valid point. I have 9 human languages (not all of them great, the Russian has rusted away hideously), and it's true that books and classes just give you the "tools" -- you then need to get your arse to that country (admittedly a bit tricky for the classical languages and sign) and use those tools to build the language for yourself. But, there are good text books, and not so good ones. For Classical Greek, I still recommend the book by Crosby & Schaeffer. You float on air through it; and if you know German or Russian declensions already, it's effortless.

p.s. Gibberish and typonese are my first languages ;}

LOL I do not half assed insult and then try to hide that this is what I am doing. Your post here is insulting and you try to hide behind saying that you are not going to get drawn into my trolling.

Now once again, your anti-tech thread was highly insulting, you meant it to be insulting and then in the last paragraph tried to say it was not meant to be insulting. You have called multiple people in both threads trolls for even the slightest disagreement to your own posts. Every time you have called them trolls and said that you will not be drawn into their trolls posts. Yet anyone can look back and see that you are the only one throwing out that insult.

I am not apologetic, you have insulted multiple friends. Your ideas are ludicrous and if you do not agree with that assessment then post the links here and let everyone see. I will continue to make fun of any attempt to change the wiki to something like this:

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

" The above is an industry-standard format that has been used in reference manuals world-wide for decades."

BS. I call it like I see it.

Really? Let's see!!


Hm... So... That's you not taking sides, eh? Wow..

You say words similar to "oh, no.. i didn't say that to be insulting at all!! it's just that..." a lot, don't you?

edit: and to stay on track a bit, the wiki is a more of a reference guide than a primer but in RL, I rarely pick up my old primers and frequently use the reference guides. Once you start to grok a language, all that primer stuff just gets in the way. A primer would also be good but replacing the whole wiki with something like that would just be silly. /me votes for more examples and extended discussions in.. er.. i dunno.. maybe the Discussion pages.

Ummmm..... Has anyone noticed that this shouting isn't going anywhere? Nobody has changed anyone's mind, and most people in both forums are sitting on the sidelines.

I can't disagree with that. However, the point I'm trying to make is I'd like to see the wiki be more than just a dictionary. I'd like it to be more like a text book. It shouldn't just list the what, but also instruct on the how and the why.

Some here are under the impression that the what would necessarily be diminished somehow by the mere presence of the how and why. I couldn't disagree more with that assessment. To go back to the text book analogy, every text book includes a glossary. If all one wants is a dictionary, one can easily flip to the glossary and ignore the rest. But if one wants to learn to use the material the dictionary contains, that's where the rest of the book comes in.

I don't think anyone here is trying to say the wiki in its present form is bad. It's actually very, very good, for what it is. It's just incomplete is all. It would benefit greatly from including information on grammar in addition to just vocabulary.

Sindy, if you consider an honest opinion about a section of the LsL Wiki to be "insulting"... LOL sorry, I think a little thicker skin is in order.

I commented on the WIKI, not a person. I didn't point a finger, name any names. I was under the impression the whole purpose of that thread was to provide feedback on the Wiki itself. I'm sorry you see that as an "insult".

Seriously, you and Jesse need to chill.