Scripting 101: the Wikibook

Great point. Are you willing to take a stab at writing a preface? It would undoubtedly help focus discussion by the contributors here on exactly those issues. Or is it premature, in the sense that reading the preface, potential contributors might say to themselves "Well, my idea doesn't really fit within this scope" instead of going ahead with their project and changing the preface?

You make a good point, Ellie. But the LSL Portal already has a section for tutorials, with "LSL101: The Wikibook" being just one. Do you see an advantage to incorporating tutorials like this into a book-like structure, rather than being independent of it?

I'd be glad to give it a shot. Having written a couple of textbooks, though, I have learned that the preface is usually the LAST thing to write, not the first. Even when I've been the sole author, I've found that my ideas have changed during the writing. If I'd written the preface first, I'd have to redo the whole thing. That's even more likely if the writing is collaborative. You're quite right that a preface now could feel like a straightjacket.

So....... sure, I'll give it a try, but I'd prefer to wait till the team has enough written to get a feel for level/scope/style/organization.

I started creating some pages, but almost immediately discovered that Zai Lynch, who devotes a lot of effort to the LSL Portal, was restructuring/renaming them, which got me pretty confused. I IM'd him and we talked a little. He hadn't seen this thread at all, but said he would try to read through it tomorrow and then share his thoughts on organizing the pages so that it meshes well with the rest of the portal.

Bottom line: You might want to hold off on adding new pages until we've worked through those issues. Apparently, if a page gets renamed while you are working on it, you can lose your most recent edits.

This is why I hate wikis. Anyone can go in and make changes to anything if they want to put in the time. Editing for spelling is one thing, but editing content and structure of an article or page without talking to the writer and getting what they have in mind would really annoy me.

Yes, it was an annoyance. But Zai was apologetic, and no great harm was done. My experience with the Wiki has been mostly editing existing pages or adding a new one which was modeled after a similar one, so I wasn't sensitive to the need to consider things like Wiki name spaces. I'm glad we found out earlier rather than later. I don't imagine it will be a long term problem.

As to the presentation models, I really didn't have a plan or a real suggestion. I want to provide a link to an article that will give them the background they need, in both scripting and possibly the topic too. If you are thinking about a by topic presentation, might I suggest looking at the LSL Categories for ideas?

So far there is something critical missing from the tutorial... an explanation as to how understand the LSL Portal content layout. The layout is a bit unusual for beginners and editors alike. It takes getting use to and could use some explanation. I'll provide the information for it but it will need a wordsmith to polish it.

I'm thinking it should be in something akin to a Chapter 0? After all, the user isn't going to be working through the tutorial in a vacuum, they are likely to be looking at the documentation at the same time.

----

As to the page titles, I'm not sure, I'm not even sure if LSL 101 should be classified as part of the LSL Portal. I don't think the LSL Header belongs at the top of each of it's pages; it has it's own sidebar. If it's not in the LSL Portal or any of the other Portals, it doesn't have to abide by the rules set down in the Portals... which means the page title rules don't quite apply. The LSL Portal doesn't have any guidelines for tutorials, so you have free reign. Maybe the tutorials should be an annex of the LSL Portal... but I digress.

As to moving the articles, I think it was premature without having a conversation first. Premature, considering we haven't even decided on the presentation. We are talking pre-alpha.

I've begun adding some content. I hope people find it to be along the lines of what we have discussed. Have to take a break now, though, because I have other priorities for the next few days but if people are happy with the approach I will continue just as soon as I have time.

I really like your writing, Prajna, and your elaboration on the https://wiki.secondlife.com/wiki/LSL_101/A_Gentle_Introduction page

Your additions to https://wiki.secondlife.com/wiki/LSL101/Simple_Script_Skeleton introduces new concepts a lot faster than I had envisioned for the "gentle" introduction. Did you see that as all being one "lesson" (as opposed, say, to that page being a safe place to get some words on "paper"?

On another note, the sidebar template that currently says something like

LSL 101: The Wikibook
* Preface
* A Gentle Introduction
* Simple Script Skeleton
* LSL In Focus
* Library Functions
* Miscellaneous

was added by Zai, not me. If the gentle introduction evolves as I imagine it, I would guess there might be something like 50 "lessons" (I'm just pulling a number out of the air here). The whole wiki book might eventually grow to be hundreds of pages. In that case, I don't think putting an entire table of contents on each page would work well. (I mention that here in case the existence of the TOC suggested I had a much less granular approach in mind for the gentle introduction.)

Thank you Omei.

I'd love to say I had some great scheme in mind and I envisage it being done in such and such a way but the truth is I just sat down and wrote and polished a little. I think it could be broken into sections on different pages but I started with Jesse's idea of a structure or skeleton and worked from that. It might make sense to have the states on one page, events on the next, variable types after that. For me it is easiest to write all on one page because that allows easy reference back to what I have already written so that I can keep consistency, continually review what I have written and so on. But that may not be the easiest way to access it from a usage point of view. For me it is easiest to work this way and then to restructure it, if it is seen to be needed to do so, later.

I think things are not introduced more quickly than is necessary but there are undoubtedly things that could be expanded on. I digressed into a brief introduction to hexadecimal numbers, for instance, which is not something you would expect to find so early in such a document, but only touched them lightly (links can lead people to a deeper understanding if they like to follow them). Equally, I have tried to resist the urge to dive into subjects near and dear to my heart, like commenting and style, so that it doesn't wander too far from the idea of developing from the base structure of a script.

ETA
I added the TOC because at the moment it is quite small and it does provide some navigation, of which there was none otherwise. At minimum we should have a previous and next topic link.

Prajna, I forked the https://wiki.secondlife.com/wiki/LSL_101/Simple_Script_Skeleton page, putting your latest version at https://wiki.secondlife.com/wiki/LSL_101/Simple_Script_Skeleton(A). I know I could have simply removed text that I wasn't ready for, and the Wiki would have saved it, but I didn't feel good about the implication that I was in some way rejecting yours. I would just like to write some more in the slower moving style I have in mind. I'm beginning to see that there may be a pedagogical issue that should be verbalized. I'm inclined to teaching in what might be called a "progressively deepening" style. Fox example, when introducing concept X, I don't feel compelled to explain X in depth. How deeply to treat X depends a lot on what is needed to understand the example at hand. I'm very comfortable saying "there's a lot more to this topic, but we'll learn that in due time."

I would like to write a half dozen or so "lessons" in this style, and then get more feedback here in the forum. This certainly is not the only way to write a textbook, and may not be the best choice here.
If you're so inclined, you could do a parallel version of how you would start, and we could compare them.

Sounds like a good idea to me. If this is going to be "the book" on LSL, it should certainly address the LSL Portal. Why don't you provide the brain dump and see who wants to wordsmith it.

Yes, the list from the Portal's LSL Language Reference pane, i.e

* Constants
* Events
* Flow Control
* (llXXX) Functions
* User-defined functions
* Operators
* States
* Types
* Variables
* Errors

seems like a good starting list for in-depth articles on language topics. Others might be Block structure, Variable scoping, Expressions, ... . We already have a good start on the Variable Scoping article earlier in the thread.

(In my proposed table of contents, these articles would comprise what I termed the "LSL In Focus" section.)

Seems like I have done a parallel version, linked at annex (A)

I didn't hear from Zai today. But the reason he changed my page titles was to create a Wiki namespace especially for the the LSL 101 Wikibook. I'm actually not sure of all the ramifications of having our own name space, but I'm willing to accept that it's a Good Thing. To put new pages into the new name space, start their title with "LSL 101/" instead of "LSL 101:" or "LSL_101:".

Could be interesting.

Though I'm more of a fan of LaTeX typesetting, a wikibook would make an excellent desk reference* for the LSL wiki -- something I've highly desired for some time, without wishing to mirror and typeset the entire wiki.


So, count me in on the interest. Feel free to poke me by email or PM as well, should you need anything from my own projects or LSL101.


* Assuming that's included, alongside an excellent tutorial set.

Well, if there is to be a gentle introduction, there has to be one for each kind of beginner.

More, better, newer tutorials in the Wiki that share more detailed information about the innards of LSL would be very useful.

I mentioned *diagrams* before. Here is an example of what I meant...

I can write something like:
--WIKI on
Suppose you have two rotaions, r1 and r2. A new rotation

rotation r3 = r1 * r3;

is the same rotation you would get by doing r1 followed by doing r2. Don't think about the fact that the '*' is used. Combining rotations this way is really more like adding them together.
WIKI OFF--

I think a lot of beginners would love to see a diagram to go along with that. Better yet, a video

By desktop reference, do you mean a nicely printed copy? I hadn't even thought about the implications of trying to do that.
This made me stop and think. I've kind of been focused on the "beginners" aspect of the Wikibook. But the biggest issue for more experienced scripters, I think, is learning how to navigate a successful passage through all LSL's limitations. If you were to take one of your projects that you'd be willing to open source, and talk about it from a design perspective, I'll bet it would be a fascinating read.

Ah, rotations. What a good topic!

Is that an offer to start a tutorial on rotations if someone else will illustrate it?

It's quite useful to have a desk reference for those days you feel like reading a dead tree book.

E-Ink will replace that need somewhat, but for now, dead trees are just easier on the eyes.


Certainly. I'll have to think up something outside of 3D design and sculpties to dissect -- most likely, how mirroring works. It's a neat subject with a good deal of Black Magic involved.

Be sure to give me a prod by PM if that comes up, so I remember.

I already did some of the editing of the Rotation sections of the various Wiki's, which everyone agrees are still in horrible shape.

My i ask to volunteer for creating a thriller machinima series named "the Rotator I/II/III" ? i am sure i can get someone from the machinimatrix to put hands on that ... So tell me early, where i can find the draft ...

That's a good point, Lee. For some topics (like rotations), there is already a wealth of information written at http://wiki.secondlife.com/wiki/Rotation. That text is available for anyone to base a Wiikibook tutorial off of.Cool!

I am very interested in classes for scripting, i want to know HOW!