Is the scripting wiki helpful to you?

Over in the scripting forum, there's currently a thread discussing possible ways that the official scripting wiki at http://wiki.secondlife.com/wiki/LSL_Portal might possibly be improved.

I know many builder friends who have tried, and then given up, to write the simplest of scripts, despite all the material available on the official scripting wiki.

So I'd like to poll scripting lay people / dabblers or would-be dabblers who have gone to the wiki before what sums up their experience with it. It may be that it's just fine as it is right now, and hey, if it ain't broke, don't fix it, right? If you haven't looked at the official scripting wiki ever before, then this poll won't apply to you.

I use them all. More information is better. cross linking wouldn't hurt either of them.

I still find myself using the rpgstats wiki because of the much better responsiveness (all official SL websites are subject to random slowness, blech) and more examples, but I do like the official wiki and use it quite frequently.

All wiki sites I've ever seen suffer from discoverability and navigation issues, and pretty much universally suck in that regard, but since I don't know what can be done (or rather, what LL would actually get around to doing) the only thing I would suggest is more examples.


.

I use google to search all three wikis at once.

LL should host the LSL wiki, it's much, much better, but down half the time.

I just like to see more examples and explanations. When I cant find then I try to find other places.

How you do that?

One way to do that is to go to

http://www.google.com/coop/cse/

and create a custom search engine that searches those domains.

Here's one to try. The urls they give you for them are really awkward urls. http://www.google.com/coop/cse?cx=009725697835091190408:bdjugumdqvs It could probably use some improvement; I just made it a minutes ago.

The current Wiki looks like it was designed to be machine readable.

I prefer the old 'back of a toilet door' style.

Readability is perfectly fine in my opinion, layout is OK too. The key problem is it is SO slow. I mean, painfully slow. There's no need for it.

In case anyone is wondering what spawned this thread... it was a thread in the Script Tips forum.

/54/87/317701/1.html

To give you a taste, I'm calling for suggestions on how to make it better. Here are some prompt questions to help focus the topic:

1) What sort of information would you like to see?
2) How would you like it organized?
3) What aspects of the documentation are most important to you?
4) What is missing from the documentation?
5) For which topics would you like to see articles written/improved?

If you want to weigh in, respond to this thread or the one in script tips. We are always looking for new fresh ideas. New wiki authors too.

/54/87/317701/1.html

Strife (and others), thanks so much for your efforts on this. Before I get to your questions, allow me to repost an assessment I wrote four or five years ago, of the available scripting documentation at the time. While things have gotten considerably better, as the wiki has replaced the old LSL manual, unfortunately most of what that assessment said still remains true to this day.




That last paragraph should now be ammended to say "That was was five years ago, and I'm only marginally closer..." With that in mind, let me now address your excellent questions, Strife.



More than anything else, I would like to see a plain English walk-through of the basics of writing some simple example scripts, from start to finish, complete with absolute beginner level explanation of the why behind each step taken. The wiki in its present form does an excellent job of listing each command, and a thorough, if not entirely reader-friendly, job of explaining what all the variables in each command do, but there's no instruction for how commands are put together to form a whole script. If the reader lacks programming experience, the wiki isn't of much benefit.

To go back to that great Star Trek episode, even when the crew of the Enterprise finally figured out how the Tamarian language worked, they were still no closer to successful communication with them, as they didn't know any of the stories the language continually referenced. As Data put it, "The situation is analogous to understanding the grammar of a language but none of the vocabulary."

With the scripting wiki, we've got exactly the opposite situation. We know all the vocabulary, but none of the grammar.



I think the current organization is very good. It just needs another section added to it, for "Intro To Scripting 101", and for other in-depth articles.



Documentation for ANYTHING should be well understandable by readers at all experience levels. In addition to the technical language already in place, there should be plain English explanations of what it all means, on every single page. As they say in every writing class in the civilized world, always write as if your reader knows nothing about the subject you're describing. That philosophy should apply to technical documentation as much as it does to every other form of writing.

To give you an idea of what I mean, I was able to learn basic HMTL in 2 weeks, having had no prior experience with it or anything like it, simply because I had the good fortune of finding a book on it that was extremely well written. On each and every page, the author spoke plain English both before and after demonstrating the command syntax, to give the reader a full understanding of all the what's and why's for everything. It was really well done.

If there were a similar volume written on LSL, I have no doubt I'd be scripting like a champ right now. But since all we've ever really been given has been a listing of commands, along with a few "Darmok and Gelad" style writings here and there, I've never been able to absorb much. The same is true for an awful lot of people I know.

The book I mentioned is called "HTML For the World Wide Web" by Elizabeth Castro, by the way. Check it out if you want to see what I mean about the writing style. It's really, really good.




As I hit on in previous points, what's missing is two main things. First we need an "Intro To Scripting" section, to teach the basics of how a script is assembled, from start to finish. Second, we need embedded explanations in layman's terms for just about everything. At present, the available documentation assumes way too much fore-knowledge on the part of the reader.

Again, check out "HTML For the World Wide Web" by Elizabeth Castro to see how, at least in my opinion, technical documentation SHOULD be written.




Intro To Scripting is the most crucial one. From there, perhaps some more advanced topics, which would build on the knowledge in the Intro section would be in order. Perhaps subjects like "How to set up a script to perform more than one action" or "How to make an object do _________". The important thing is not so much the specific topics, though, but how the articles are written. Again, the writer must assume complete ignorance on the part of the reader in each and every article. Full explanations MUST be given for why each step is taken.

I really wish could be of more help with writing some good solid articles to help people get started. But since I know so little myself about the how-to's of scripting, I'm afraid I can't be of much use. About all I could really do is read an article, and then report how much I feel I did or didn't learn from it. If you feel that that would be helpful, feel free to call on me for that purpose, and I'll do what I can.

[long rant about the piss-poor educational system and the lack of general understanding of basic software concepts deleted]

Sometimes I really do despair. This stuff should be covered in junior high. In today's world it's more important than knowing about evolution or whether Pluto is a planet.

Agreed, but that still wouldn't help the rest of us. When I was in junior high, it was the mid to late 80's, and "computer class" consisted of learning how to write text-based RPG's in Basic on a TRS-80. Computers at that time, for most people, were just a curiosity, something which if built in a cave, Richard Prior could use to steal pennies and to kick Superman's ass. Very few, if any, people imagined that the world would one day revolve around them. Some of us had heard of this thing called Windows which had just been invented that was somehow supposed to be cooler than using Basic, but none of us knew what it was. There was no Internet, no such thing as a "personal" computer in much more than name.

After junior high, I didn't touch a computer again until college, and then it was just for writing papers on that newfangled thing called MS Word. Windows 3.1 was brand spankin' new, and my Thinkpad 500 with its 50MHz 486 processor and its tiny black and white screen were the envy of my classmates, primarily because it could play DOS Mortal Kombat and Jill of the Jungle.

Did I mention we also waked up hill both way to and from class?

So while I completely agree with you that basic programming knowledge is a crucial skill in today's world, and that every child should learn it at least to some degree, that wouldn't change anything for today's adults. Isn't this thread about what to do for us?




I wouldn't necessarily agree that it's MORE important, but it's certainly at least AS important.

Ok, I think I have, thanks to Chosen, worked out how to keep the noobs from screwing up our valuable technical reference by insisting it be verbose and aimed at kindergarten-level aliens... We just write a newbie's guide and let them cut their teeth on that before graduating to a point they can make sense of the meat of the wiki. Do I need to volunteer Strife? Is it easily linked? I have never done more in wiki terms than correct a few spelling and grammatical errors in Wikipedia but I can script and may even succeed in explaining how to do so in layman's terms.

'70s for me, and I was writing simple graphics games on an Apple-][. By 1984 I'd written a text-mode "virtual world" program and met my wife online in a multiuser role-playing game I was running. If you'd asked me in high school if basic computer science would be a standard part of high school ten years later I would have answered "absolutely". It's thirty years later and it's still not there.

"Can you program?" "Well, I'm literate, if that's what you mean!" -- a hypothetical exchange from the year 2000 as envisioned by Robert Anton Wilson in 1974. Boy, was he optimistic.
Late '80s? No Internet? No personal computers? My entire career is a figment of my imagination? *boggle*

No, really, this stuff should have been in EVERYONE'S high school curriculum by the time you were in high school.

Hmmmm... Is there anyone who shouldn't find this comment offensive?

Sounds like your upbringing was quite different from mine. I had no idea a computer was anything of importance in 1984. Heck, we'd only just gotten cable TV for the first time. The most advanced piece of equipment we had, outside of my father's study which had an Apple III in it (yes, an Apple III), was that corded remote control with the channel slider on it.

We had bicycles and baseball mitts and we actually went outside and stuff.




Well, there was no Internet as far as most of the public knew. If you were using its then form for a living, that's a different story, of course. The thing we all now think of as "The Internet" didn't really take off until well into the 90's. Whether that's because the technology changed or simply because the public perception changed, I have no idea. All I know is in the 80's, if someone had said "Internet" to me, I would have guessed it was some sort of commercial fishing tool.

And while there were things labeled "personal computer" I didn't know anyone who had one. My dad had that Apple III, but that was for work, as far as I knew. It was pretty much "He's an important scientist. Of course HE has a computer." He also had a whole bunch of laboratories with laser beams and liquid nitrogen tanks and chemicals and all kinds of equipment nobody else would have. His computer, to us, was just one more of those strange scientist things. That they would one day be used for literally everything hadn't occurred to us.




I'm sure you're right about that. The good news is things do seem to be changing for the better. I was just told by some friends who are teachers that their junior high school now teaches Maya. That's not quite the same thing as what we've been talking about, obviously, but it is along the same lines. The 3D artists and animators of tomorrow will have a 20-year headstart on how most of us had to do it. Hopefully the same will be able to be said of programmers as well.

The "newbie's guide", or whatever you want to call it, is only half the answer. The other half is adding a small section to each page that says in plain English, "Here's what this function does, here's how it's used, and here's why." The exact same technical info would still be there, completely unchanged, in the same format it's in now. It would just be preceded and/or followed by some paragraph-form writing, which you could easily ignore if you don't need it.

It's not about "screwing up" the existing stuff. It's about supplementing it with co-existing layman-friendly information, so that everyone can make sense of every page.

Sorry if it offended you Rolig, but I just came over from the thread that inspired Chaz to create this poll in the hope of drumming up support for dumbing down the wiki. Why dumb down something that is very useful and optimised as a reference, which is what is becomes just as soon as one gets past the initial learning curve of being confronted with LSL (and possibly even the first programming of any kind that someone has done).


It is about screwing things up if it means those who do use it as a reference (for which its current format is most suitable) have to scan over paragraphs aimed at newbies in order to get to useful reference information. Everyone can't make sense of every page and without some introduction to scripting before they even approach the wiki they most likely can't make sense of any page.

You, along with a number of others, suggest that it be all things to all people but that is not possible without compromise: it is not useful to have to wade through verbose explanations in search of technical details that can be expressed succinctly. Nor, as you have observed, is it helpful to try to learn a subject by struggling to make sense of a collection of terse, unfamiliar technical terms.

So why don't we bite the bullet and set about producing something that is aimed specifically at introducing newcomers to LSL scripting and, at the same time, improve the utility of the current wiki as a reference. Probably I should have stated it thus in my previous post.

Sorry Rolig, I know you expend a great deal of time assisting people with scripts and I should have been less scathing. I have just waded through 120odd posts on this subject and it has been frustrating to see people trying to turn the wiki into something entirely different than it is.

Not as of a few years ago when my son was in high school. They had programming courses but they had absolutely no idea how to teach programming. You want to get kids interested in it, you show them how to program cool shit, not accounting programs. Most of them won't ever get a chance to program cool shit professionally, but so what, you're teaching programming here... not accounting.

I agree with you Chosen, on there needs to be a better newbie guide written. It took me almost 2 months to wrap my head around event driven script, coming from a C++ background. Basically, there needs to be a "text book" written for people who are trying to start out, with examples, and projects. The only problem with this, is that it is very time consuming for who's benefit? Sure, more scripters would be great, and if you have the desire to actually learn the ins and outs, then the LSL 101 guide would be great.

What I often run into, and I know you do in the texture field, is that people just want to modify a script, or in your case, know how to use a specific filter, or how to do a nice little trick. I find myself trying to explain certain things to people who have no concept of how to do any of it, and it doesn't help that most freebie scripts take a half hour just to walk through to know exactly what they are doing.

So, I guess it's two things, a complete LSL 101 for beginners, and maybe a second section on how to modify scripts.

PS. I know the book about LSL you are talking about, and actually it is very good, anyone who is serious about learning LSL and can afford the book, should look into it.

The poll was created with a view to seeing honestly what people felt, however they felt, and the range of possible answers I provided shows that.

I am not going to react to your comment otherwise, as that would just get us way off track.

This might be a good point at which to point out that part of the stated mandate of the official wiki reads: "It is intended to help scripters of all skill levels."

If one wants to change the mandate of the wiki to excise that part, that is perhaps a separate topic altogether.

The mandate can be viewed in the first para on this page:

http://wiki.secondlife.com/wiki/LSL_Portal