Wiki Wiki Wiki

The LSL Portal as you may know is hosted on the SL Wiki and is the Official LSL documentation. Despite it being the official documentation it is almost entirely user written and maintained. Oddly not many of the community participate, which is the reason for this post... now I've spent a huge amount of time working on the documentation without much feedback from the community and this makes me uneasy. So...

I want to know what you think of the documentation.
I want to know how it can be improved.

Here are some questions to contemplate.
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?

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

Templates scare me!!

You're doing awesome, Strife - keep it up.

What would I do without it??
I would be lost.
Not one day pass without I visit this wiki or the old lslwiki.net.
I prefer the colors and layout of the old one.
I love the samples and snippets found in the old one, it was where I learned LSL
The Official wiki I turn to when I want to read about new functions not found in the old one and when I want to learn what is official
The wiki is my bible
Strife, you do a great job!

;0 dunno if i can offer any answers to your q's strife, but i've been crowbarring multi-lingual support into my scripts and found that perhaps some of that could use updating. i'll see if i can contribute a bit to that...

i love the wiki and use it often but would like a better search system and more examples.

i learn the best with looking at the examples because english isn't my natural language and it can be difficult to understand certain sentence.
because i often don't know what i am exactly search for i would like a kind of fuzzy search.

Not sure if this is what you mean, but specificly, the rotation page really needs visual aids with the text. Lots of people get confused by rotation and rotation manipulation.

My problem is that the search is useless. If I type in a word, chances are high that I'll get some arcane wiki page referencing the greater SL wiki, and not the lsl section. examples: avatar, agent, animation, movement, etc. Sometimes I'll get search results, but most times I'll just end up on some page that has nothing to do with the thing I'm looking for. Attaching it to the official SL wiki was a stupid decision.

When it comes to working with LSL, I still use http://rpgstats.com FIRST. If I absolutely KNOW that the function won't be there (llSetLinkPrimitiveParams, for example) THEN, and ONLY THEN, will I look it up on the official wiki.

The official wiki reads like stereo instructions. No, that's not even correct. it reads like the back page of stereo instructions. The one that gives you all the technical jargon and symbols. While wiki's like rpgstats, lslwiki, etc, read like recipes from a kid-friendly cookbook. The official LSL wiki reminds me of a calculus textbook, in the way that it "assumes you already know" some things that I probably don't know already.

Put simply, the official wiki sucks. It's raw, complicated, convoluted, and lacks even the barest explanations of things that really do need explaining. There are important pages missing, or unfindable, and when they are there, very often they're useless when compared to their rpgstats equivalents.

I don't understand how to use these wiki things. How to edit, how to replace, remove, link, or make new pages. I don't know the rules, or "teh w4y it's d0n3".. Maybe you could start by making a page explaining HOW to edit/add/change/link/remove pages?

I wouldn't go so far as to say that the Official LSL wiki sucks, but Winter's right. It isn't very friendly. I usually head to the old wiki first when I have a question. Its language is a bit looser and a bit more verbose, and its pages are laced with MANY more helpful snippets so I can see how a function is applied, not just how it's defined. The only thing the Official wiki really has going for it is that it's more up-to-date. It's the only place I can go to read about the llDetectedTouch functions, for example.

Like Winter, I also don't have a clue about how to modify the wiki. Not that I have a burning need to do it, of course, but there have been times when I've tripped over awkward grammar or clumsy wording and it would have been nice to get out the blue pencil.

Gonna be some huge changes needed to the wiki and it looks like it will be sooner then later. LL is working at making C# & maybe F# useable:

http://wiki.secondlife.com/wiki/User:Babbage_Linden/Office_Hours/2009_04_22

Honestly, http://lslwiki.net/ pretty much has everything I need except for some pretty recently added functions. So my answers would be one or both of:

1.) Port info from lslwiki.net to the official wiki. I'm aware of the copyright issues, so I'm not sure what you or we can do about this. Start contacting lslwiki.net authors and requesting permission to reuse content?

2.) Get significant LINDEN participation as well as resident participation. I have always seen it as Linden Lab's responsibility to document their own interface. Often others can only grasp in the dark for both the behavior and the intended contract of an API element. This is not an "instead of" resident contributions, which can obviously fill in the gaps much quicker than getting a paid resource to do similar, but an "in addition to." It would be very helpful in this case to have an obvious separation between official documentation and user-contributed comments, examples, etc.

Also, with the new changes to memory (been the hot topic) perhaps, if possible, get exact numbers for how much memory the stuff uses, not force us to speculate and test left and right to see. It would be nice to also see how these functions given to us, handle memory issues, I've mentioned it before, but would be nice to see a clear defined, what is passed by value, what is passed by reference etc.

Basically, it's what Heewee said, we need much better documentation from the people who wrote the code, not end user speculation.

The Portal is slow too, I don't know if you can speed it up or not, but I have both the portal and lslwiki.net bookmarked. I have more then on one occasion, gone to the portal to look up a function, click on that function, wait for 10 seconds, hit the lslwiki bookmark page, go to their function page, click on the function, have it come up, and read it, all before the portal page has loaded. It gets really frustrating when I need to look up a simple thing, when it takes a minute just to get to the page.

I'm with Hewee and Lazink on this. I use lslwiki.net rather than the official wiki. It's faster, has more (good to understand) examples, is well organised and I usually find what I'm looking for after one or two clicks...
And - as Lazink says - lslwiki is much faster than the official one...

;0 hey wtf? ;0 where'd all the 'script library' posts go?? :\ i just went to visit and all that came up were two stickies. (still says 450+ posts in the index though... forum buggies lately?? :\)

I truely detest the software that lslwiki uses. Just drives me nuts..

Search could use some work and it'd be nice if LL put it on something a bit beefier than an i386 but the official one is where I always go.

Good job, Strife!

Go to Advanced Search and increase your date range.

So far the feedback is looking useful.

Here is what I'm hearing and my initial thoughts:
* More examples, samples, snippets - This isn't hard just time consuming. I'll try to get myself in the habit of writing an example/snippet per article edit.
* Less scary templates - Better documentation of the templates might make them less scary but I doubt it. I have been cleaning up the templates, making them more readable and maintainable.
* Visual aids - This is something we need no doubt but it isn't one of my strengths.
* Better search - I can't do anything about this, you need to take it up with LL.
* Speed up wiki engine - I'm not going to do anything about this, get LL to throw more server time at it. I could simplify some templates and I have been trying to do so but I'm not going to sacrifice functionality. On the whole the LSL Portal articles are more complex than the LSLWiki articles, MediaWiki allows us to do some really cool stuff and we take full advantage of it; the cost is articles that are 100KB.

Winter: Your feedback is exactly what I want to hear. Which leads me to another question (which I'll add to the OP)...

5) For which topics would you like to see articles written/improved?

I've created a page which I invite everyone to edit (look ma no templates): LSL topics they would like to see (better) documented.
https://wiki.secondlife.com/wiki/Requested_LSL_Articles

I hate the word "Caveat" being used there.

A WYSIWYG editor would suit me, and I am right that you can't put pictures there?

The content seems a bit skimpy. Not enough examples.

The code sample font size is too small to suit me, and it's not something that can be readily well fixed with either text zoom or page zoom.

None of the choice of style other than the default one are any better, to my taste.

It's good work that's been done, I don't mean to sound too negative, I'm not in a good mood at them moment.

I really just wanted to say I really really dislike the word "Caveat".

I ask this with all seriousness, do you have any suggestions as to an alternate word or phrase? The name of the section isn't set in stone, it wouldn't take long to change (it's an easy change).

Sindy: I too detest the Wakka Wiki engine, it's why I work on the LSL Portal... I got sick of dealing with it's shit. By the way, I'm BW/BlindWanderer on the LSLWiki, and anyone who wants to can port my contributions to the LSLWiki to the LSL Portal; this is me granting permission. Just be sure to say you are doing that in the edit summary, otherwise I may embarrass myself while editing.

Warning, to be literal, although I think Comments or Discussion would work better.

I was being serious, although I will grant it didn't sound very serious, even to me. It's bothered me since the first time I saw it.

i use the site alot and i like it thank you
the few things i live with that bug me,
not all functions listed on one page its now 3 pages.
the search never worked well.
but really thank you for all your time and effort its been a great help

Warning works but that seems a bit strong, The serious warnings get a dedicated box with an icon at the top, maybe "Beware" instead?

I didn't want you to think I was rebuking your comment ("Do you have a better idea? No? GTFO" - not my goal).

;0 doh thanks! ;0 there we go...

ooo! yes please. Thanks =)

Examples of how to use some of the more obscure parameters. Like this one for instance: VEHICLE_REFERENCE_FRAME. I know that when I use this I can roll and bank my vehicle but I have no idea how to relate this to the current rotation and power being applied by the motors, so I end up all over the place. I tried using VEHICLE_BANKING_xxx for this but it doesnt seem to do anything much and I dont know why.

Would be really good if some knowledgeable person could explain these more obscure kinds of things to us on the wiki.

The portal wiki has come a LONG way, Strife, great work. I have to admit, though, that I usually go to the old lslwiki.net first, because its search function works. The search on the portal, as others have said, returns so much crud that it is useless. Once having found the command/page/ needed, I often then look up the command on the portal as well.

Some explanations on the new portal are actually better - for example, I found the explanations of the newer particle parameters more useful than lslwiki's. Someday I should check and see if it references the particle lab for a full set of sample scripts with demos of how they look ... I suppose I COULD add that myself, but its the kind of edit I'm always shy about making, not knowing whether references to inworld examples are a good idea.

I would love an explanation of LSL memory utilization, as well as recommendations for when to use Mono and when LSL is actually better.

More examples, yes.

/me also makes a note to check the page on script permissions to see if it cautions about the effect of permissions when you edit or transfer the script/object when script owner and prim owner are different.
.

"Take Note" would suit me, or "Comments". I see things in that section that are more just comments than warnings.