Wiki Wiki Wiki

Feeling guilty for using but not adding to the official wiki so much, I just went to add a llMoveToTarget note about a SVC-2441, which LL will probably never fix because people have relied on the buggy movement for so long..

I wasn't just sucking up when I said I liked the official wiki - overall, it really is nicely done. I just don't know how to edit it. Editing mediawiki pages in-general isn't overly hard and I know what I want to say but.. where & how do I say it? The wiki's like that piece of sushi that's just so beautifully put together that you're afraid to poke it because it's so nice. This more than anything else has kept me from contributing in the past. Many times.

So.. Yeah, templates are a little scary and all that but what I think would help the official wiki the most is finding a way for people to contribute examples/notes without having to think about it. No idea how to do that but I think you'll get more people adding info if you make it easier for them.

(and I finally did figure out how to add a note about SVC-2441, though I had to actually think.. wasn't too hard but I still had to think, which is something I like to avoid)

I feel (I realize this is possibly just how I feel) that the template makes the mistake of starting the pages with the jargon. Picture the times when you go to the Official wiki. You're already brain-dead, should have been in bed hours ago, and you been fighting with LSL all that time. First thing on an Official wiki function page you get whammed between the eyes with the technical specs. Whereas I bet what you want are: what it does, and some examples, so you can see if it's anything you're interested in. If it is, you can read down to the specs and caveats. If it ain't, you can whip onto the next possible function that might save your butt that night.

Perfect Example: llSay

http://rpgstats.com/wiki/index.php?title=LlSay


vs

http://wiki.secondlife.com/wiki/LlSay


Fundamental to all this is I suppose a decision on who the audience is.

I like "Take Note", "Be Aware" was something that just struck me ("Beware" just didn't feel right). "Comments" isn't what I personally envisioned for the section, that's more what the "Notes" section is for.

About the layout:
I try to distill most comments to it's information and move the actual comment into Notes, providing a link between the sections. Notes is where you can write just about anything as long as it's useful; if something is not useful but relevant then it can go into Deep Notes.

Deep Notes (which could possibly use a better title) is for everything you don't need to know, which is marginally useful at best. Like the function history. There is a dedicated comments section, (i think it comes after deep notes) but it is intended for commenting on feature requests.

The idea is to have the most relevant information at the top and go into more and more detail as you go down the article. First you get a summary and syntax, then you get critical notes, and detail usage, then you get related articles and general notes; finally you get what is left over.

My big contention with the LSLWiki is that the information is all over the place. If you want to know a specific detail of a function, you have to read the entire article to find it and the relevant information is buried in paragraphs. This is what a bullet hierarchy is good for. Paragraphs only give about 1.5 levels (.5 because of first and last sentence are summary/conclusion, but the stuff between could be intended to be anything); what is really needed is at least 2 to 3 levels. It makes finding information easier when you can have distinct levels.

I have to agree the rpgstats article in this case is superior in it's initial presentation. It's succinct and to the point which the Portal article isn't. I'd love to pouch the content but for copyright. I will say in my own defense, that I didn't write that... but I can't claim complete innocence either, I didn't fix it.

I've added llSay and friends to the todo list.

@Bad search engine: I'll try to add LSL Category references in Help Portal articles (like the mentioned "Avatar" one to Category:LSL_Avatar, etc.). Besides that, it's a good idea to use a Google search for the wiki. Go to Google and add
site:wiki.secondlife.com avatar
as a search term. Rand Linden mentioned that he'd like to implement such a Google search in the Wiki, though I can imagine it will take some time till it's live.

@ How to edit pages: There is a documentation on how to edit pages. On the left sidebar, you'll find a link named "Help". This one gives a short intro about wiki markup. It also contains a video tutorial by Torley. In addition to that, it links the "Quickie Wiki Intro" article, which provides detailed information on how to create pages, how to link pages, categorize pages, move pages...
https://wiki.secondlife.com/wiki/Quickie_Wiki_Intro

LSL Template specific instructions are stored at
https://wiki.secondlife.com/wiki/LSL_Editing_Primer
as well as at the templates itself.

@WYSIWYG: They are a good idea though they won't work with the LSL templates. And stripping the templates off would result in a major headache when it comes to unify style and update content. Though there would be the possibility to create article-subpages like "Articlename/suggestion" (or the related talkpage) and add desired info to these so a seasoned editor can incorperate them in the actual article so others don't have to bother with the template markup. Would that be a solution for the concern?

If you're not certain on what's allowed or not on the Wiki, have a look at the "Editing Guidelines" (linked in the left sidebar again). These are really just basic guidelines. So I'd say in a nutshell: When it's not harrassing/spamming AND not violating copyright, just add it to the Wiki and in case someone considers it beeing wrong, that person can remove (or alter) it again. Be BOLD.
https://wiki.secondlife.com/wiki/Editing_Guidelines

P.S.: @Copyright LSL Portal vs. LSL Wiki: Just a heads-up that all articles about LSL functions are linked to their twin in the other wiki. This is a current work-around on the copyright problem. Scroll down to the bottom of llSay (for example) and you'll find a link to the llSay function in the lslwiki.net when you're in the LSL Portal and vice vera.

I just have to say, I live on the wiki, and you've done a great job. Yeah, there are weird things here and there, examples can be hard to find, or don't exist. I really like that page you set up without template, editing is something I never was able to figure out lol, but I think it might have something to do with the fact I JUST realized you had to log in to the wiki!

My biggest problem is with the search, if I already know what I am looking for, it's fine, but if I'm not sure, the search is fairly useless. I'm still looking for an example for
llScripterHead([INCREASE_SIZE,10.00,EXPLODE]); as well..

1) all the wonderful inconsistencies between page names
some are named directly for what they are llGetRot..
some are prefixed to avoid collisions elsewhere in the wiki LSL_*
and some are named inconsistently by their category, Category:*
and then there are some combinations going on with categories and the other styles

the whole thing needs Dropped a folder level, then we can use LSL_* for general topics, and * for direct references to functions. this would probably make searching a whole hell of a lot easier and specific too.

2) minor peeve.. several of the redirects for lsl highlighting go to the wrong pages, people have added redirects for a few of these but there's still some wrong or missing. there's no way on our side to correct the highlighting code, and if it ever does get fixed, all the redirect pages will be orphaned (they mostly have a format of LSL_*) (I brought this up on portal talk page once, no comment or advice last I checked)

3) examples updates: there's no consensus or even discussion of how to handle situations where examples are updated/added to one language, but the editor is unfamiliar with the other language's. originally I just added the english version if none was available, but now I just update the languages I can be clear in.

4) also minor. some foreign language pages exist in the other functions section of the function page (and in the main english listing) and very inconsistently. it makes more sense to refer to these through the language bar only, unless the page doesn't exist in that language. as for how to accomplish that? I haven't dealt enough with wiki software to even know if possible

5) capitalization. this one really hurts searching, misspelled items are one thing, but the absolute sensitivity to case makes easy searching hard... I was tempted to start adding redirects for every lower-cased version of a page that I came across... TBH it'd be a monumental task, and probably a waste....

6) dates: information can quickly go out of date, simply putting the last date edited in an easy to spot place should make it a little easier to know if something might've happened since the last edit, maybe included the last major editors name (and can probably go with the last major edit, ignoring minor ones, so that people can tag things like spelling corrections or rewordings as minor and not trigger a change in the information date)[and yes I know that signing stuff has been frowned upon, currently I only sign examples, and then inside the example comments, but this would help credit people, and make public accountability simpler for non editors]

7)general stuff: more examples, graphic demonstrations, simpler templates, most of the basic stuff you hear, a consistent manual way to add links to other places for topics that may be named differently elsewhere(like we do for functions etc with lslwiki)

Move Jira issues out of deep notes, and into the notes section, they are generally of immediate relevance, but I still find pages with them hidden away down there.

9) on the topic of jiras, perhaps a link to search jira based on the function etc name (in the title only I think would be best), since currently people have to add their pet jira's manually and that can be tedious considering the number of them... I don't think automatically adding them from jira would be useful consider the mess that jira is right now.

yeah that's all I've got off the top of my head, and I do edit when I've time (though been very busy recently, so it's not been a priority for me. mostly only when someone mentions and references it here until I get back to having more free time for this particular hobby.

PS 'caveat' is a bad habit of mine too from business culture, I like NOTE: and BE AWARE:... oddly enough I have no idea how to pronounce 'caveat' I use it strictly in writing =|

In the same boat. I offer 6 language functionality in most of my products. Sweating bricks now of course about the new parcel script limits; might need to redo them all and make drop-in language modules, instead of the admittedly more intuitive switch language on the fly via menu button.

Is an example really any different from a recipe? If anyone is familiar with recipe copyright, what's copyright is not a dish, but the expression of how to create that dish. If you modify one or two ingredients slightly (up or down or drop the salt called for, say, which any cook would do anyway), and recast the directions after the ingredients into your own words, bingo, a new distinct recipe has been born in the eyes of the Geneva convention.

Applying that to examples, there are lots of good examples on rpgstats, but we don't want to copy how they are expressed. So, we just rewrite them. Whenever they say foo, we change it to goo...

Here's an example on rpgstats on llSay page: http://rpgstats.com/wiki/index.php?title=LlSay:
integer TheAnswer = 42;
llSay(0, (string)TheAnswer);

The rewrite could be:
integer Amount = 97;
llSay(0, (string)Amount);

And voila, a new example that communicates the same thing has been born.

How many pages on rpgstats? Say 180 for now for the sake of argument. If we organized 60 people to each tackle 3 pages, or 30 people to each tackle 6 pages.... I bet we could have the re-written examples ported over to the official wiki by July (allowing for laggards.)

One of my personal favorite ways to view the wiki is the Functions listed by Function ID.

http://wiki.secondlife.com/wiki/LSL_Function_ID

However this isn't that easy to get to. I have to first get to a function page,then click on the Fucntion ID header. It would be nice if there was a direct link to Function ID listing from say the top bar where Functions, Events, Types, Operators, etc is listed.

Why do I like Function ID? Because from a chronology standpoint it makes sense. It's often only the newer functions I really need to reference at this point, and this makes finding them easier.

Have taken the liberty of adding this:

https://wiki.secondlife.com/wiki/LSL_Portal

Under section: LSL Language Reference / Functions

Have taken the liberty of adding a link to existing syntax etc help to the "welcome" paragraph. It's also accessible via the "help" link on the left hand side, admittedly, but it's not apparent what that "help" is for so I added " Please feel free to edit and add -- see here for info on how to "

Strife, the wiki is the perhaps most important source of knowledge for all things lsl. Brilliant job all the way.
A huge thank you!
Personallty i like smal clear examples with limited funktionality, and with simple and understandable syntax.
-eg functional snippets /examples

"A" examples for a good one and a not so good entrance i the function category:
Good:
llAllowInventoryDrop
llAttachToAvatar
llApplyImpulse
All are well explained, have a small snippet that can be tested in-world

less good
llAxes2Rot
an in depth explaination is not given. There is no examples

bad/missing
llDetectedTouchBinormal
nothing in this entrance
1.21 entrances are generally not described.

Maintaining a wiki is a HUGE job, so once again Thank You!
BR
ab

PS. just in case I forgot to mention it yet again... Strife, you rock =) seriously, what would we do without all the effort you've put into this and various other SL aspects, in many places... your determination, skill and profusion of content are a source of inspiration. Thank you.

Ok some follow up.

Promoting the "Issues" section into "Notes" is a good idea. Especially since bugs are important to know about. A jira link is a really good idea. I've added both to the todo list, not sure when they will happen but they are at the top of the list and they are easy to do.

-----

Now to explain the template madness. The templates do not include text in a linear fashion. The templates fit into three classes:
* Layout - Organizes and displays information based on variables and Black Box code
* Black Box - Pass the template some variables and it pulls some levers behind the scenes
* Simple transclusion - Pass the template some variables and it gives you something back, may integrate with Black Box code.

The Black Box Templates (BBT) are the hardest to understand. The other two templates make sense: you feed them something and they give you something in return. The BBTs on the other hand set the values of variables which persist after the template has finished parsing, in addition these variables can be accessed by any other template that is called after the variable is set (no scope restrictions). In this way the BBTs can add content to sections of an article by simple appending data to the end of variables that are later read by the other templates. The effect is that BBTs can add content to multiple sections all at once, instead of being forced to add to them in the order they appear in the article. The BBT method makes it possible to quickly plug content into articles with very little fuss.

On the real wiki (wikipedia) I often see "see also" links to external sites on the bottom of the page. Is there any reason why links could not be provided to the matching articles on the other wiki sites?

See Also:
rpgstats/llParticleSystem
lslwiki/llParticleSystem

etc.

I know you want the official wiki to be a clearing house of information, one-stop shopping.. but the fact is, if we can't copy the text over from the old wikis, we could, theorhetically, link to them. The information is still valid even if we don't own it.

Besides, providing these links would make it easier to get all the knowledge available on a subject, which in turn could inspire people to capsulize that information back on the main site.

We do have a link to the lslwiki at the very bottom, it's in the format:
"This article wasn't helpful for you? Maybe the _related article at the LSL Wiki_ is able to bring enlightenment."

I'd like to draw people to the PRIM_TYPE_* documentation because I've had an idea and I'd like some input.

https://wiki.secondlife.com/wiki/PRIM_TYPE_BOX

Currently you will see that both PRIM_TYPE and PRIM_TYPE_LEGACY share pretty equal footing. I'm thinking of demoting the PRIM_TYPE_LEGACY section to a subsection within Deep Notes. It is after all an interface that has fallen from favor (it doesn't even have a proper constant name). Thoughts?

(Also, what do people think about having text justified?)

I believe it's the rpgstats guy Thraxis Epsilon I think musing about when the right time is to take rpgstats down. I think he's been talked out of it so far by all the "gasps" he's heard.

I wouldn't fault him if he did. Running a wiki is a lot of hassle, (more than just maintaining content). It would be beneficial if the changes made there were rolled back into the lslwiki if that is to happen.

On the topic of pouching, It's not good enough to just change variable names, strings and comments. You have to change the underlying structure too. But regardless you have the problem that what you are dealing with is a derivative work, the original authors copyright still applies. At the end of the day it is the intent that matters, the original authors copyright is being subverted. Consequently, I only ever read the other wikis AFTER I have written the new documentation. It's safer to side step the derivative work issue by not starting with one.

On the other hand you have to consider what is copyrightable and who owns the copyright. Much of the documentation is based on the tooltips from the client (for which both wikis got permission to utilize). If you change the vast majority of the words and meaning of a sentence it is very hard to say that it is a derivative work.

I don't want to delve too much into copyright law, because in our case, no one has been talking about lifting entire structure and page, or even the smallest portion of it. Poaching (not sure where this word "pouching" came from) entire pages from another wiki wouldn't work anyway -- they wouldn't fit into the format of the official wiki, and they'd need to be so completely recast that they'd end up as new pages anyway and it would be faster just to write them from scratch -- as indeed you have.

So, to refocus, two things are emerging:

(1) page structure of the official wiki -- enough people seem to find it daunting and inscrutable and Strife has asked for ways that can be improved; and

(2) we need some workers I would say to populate the official wiki with examples.

I'd also like to add that we should consider trying (at least) to make language used in the wiki accessible to the broadest possible audience of scripters -- after all, the official lsl portal in its opening few lines gives itself the mandate to assist scripters of all levels.

There were some excellent suggestions made by Eren Padar here: http://jira.secondlife.com/browse/WEB-658

as to how some sections could be recast into plain English (which also has the benefit of being more accessible to those for whom English is not a mother tongue.)

Eren, in fact, seemed to be the kind of keener we should be bringing in on this, and recruiting as a volunteer.

Chaz IMed me and told me he'd mentioned my name here, so thought I'd hop in for a moment. Just a few quick points:

* Strife is a nice guy. He's put a LOT of work in on the LsL Wiki. That HAS to be recognized. Same for Lex Neva.

* That said. Strife is a tech. Not only that, he's a BRILLIANT tech. That means that in normal mode... he has difficulty speaking plain English when it comes to code. Like most brilliant techs, it's so simple to him he forgets how complex it can be to others.

* Strife IS quite capable-- once he's set on the right direction-- of writing in English. For a prime example of this, see llSetColor(). However, realize that the posting for that function came about only after much hair pulling, frustration, beating my head against a wall and the aforementioned JIRA post where this subject was discussed to death. That was far more effort than should have been required for such a simple issue... but it did have eventual benefits. That's something I would not be willing to go through again just to get a reasonable change on one function page.

* Thanks Strife, for posting this forum. I just regret this effort wasn't begun months ago.

* I have to agree with almost every point Winter made way back near the beginning of this thread. Strongly worded, but accurate. What Winter stated pretty much exactly echoes the frustrations and opinions people have of the LsL Wiki on a daily basis. His post is realistic and reflects the actual feelings of regular SL users, namely, total frustration with the LsL Wiki.

* It IS possible for the LsL Wiki to change... but not if people keep hanging on to the old. As I stated in the JIRA, the total format (imho) needs updated. Emphasis needs to be turned AWAY from the variable type (focusing on string, int, key etc) and instead emphasis put on FUNCTION FIRST (with the variable types defined in addition). That's a very easy thing to do... so it surprises me no one has bothered doing it. I don't have time to go into great detail here; other irons in the fire. But I said it before and it still holds true: the TYPES of variables are not as important to understanding the REASON FOR THE VARIABLES.

***
Well, maybe I'll give one example (for those who didn't read the JIRA):

llSetColor(vector color,integer face);

That is NOT informative to the average user. It's confusing and uninformative. The current Wiki listing for llSetColor has been vastly improved over its original form. But parts of it are still convoluted. Look at the example which remains there to this day:

--------
integer face = -1;
vector color = <1.0, 1.0, 1.0>;

default
{
touch_start(integer num)
{
if(~face)//quick & dirty check for -1
llSetColor(color, face); //restore the color
face = (face + 1) % llGetNumberOfSides(); //increment and keep the face number in range
color = llGetColor(face); //save the face's color
llSetColor(<0.5, 0.0, 0.0>, face );//change the face's color
}
}
-------

Geez, could this be any more confusing to new scripters? Maybe we should show them how to make the prim spin and play a tune at the same time? ;D

Maybe we could try the following ideas instead, as a format for ALL LsLWiki postings:

======================

Concept: llSetColor(<red,green,blue>,SIDE OF PRIM);

Purpose: To alter the color of one or more sides of a prim.

Syntax: llSetColor(vector color,integer sides);
where...
vector color: the RGB equivalent of the color desired (RGB values 0 to 1, 0=black 1=white)
integer sides: is the SIDE of the prim you wish to color. ALL_SIDES may be used to color the entire prim.

User note: Since RGB colors nomrally range 0 to 255, the values for the vector must be in decimal figures. To find the decimal values:

RGB VALUE / 256

Example 1: llSetColor(<0,.5,1>,ALL_SIDES); //colors all sides dark cyan
Example 2: llSetColor(<r,g,b>,5); // colors side 5 the color specified by variables r,g,b

USAGE EXAMPLE:
// Changes the color of an entire prim upon touch, then back again
default{

touch_start(integer num){
llSetColor(<1,0,0>,ALL_SIDES); // set color to red when touched
llSleep(2); // sleeps 2 seconds
llSetColor(<1,1,1>,ALL_SIDES); // changes back to default "white" color
}

}


======================

Suddenly, we have a Wiki that is understandable to just about anyone with reasonable coding experience... and can be figured out even by total newbs.

(note: I don't know how to "format" this forum... so just live with the lack of white space. LOL. Realize there can be an "advanced examples" section that shows how to tweak and giggle. But for standard code examples, it should be kept as simple as possible.)

The above listed construct could be used as a format for all Wiki listings:
* Purpose first
* Format second
* Single-line examples third
* Basic examples next
* Advanced examples next

In my personal opinion, that is THE way to write an understandable user/tech manual. Anything more complex than that and people will be left scratching their heads.

So in order to improve the Wiki it's like all of Second Life: in order to make it better, one is first going to have to tear down the mess that's there. Like Winter said... it currently reads like the BACK pages of a VCR manual. It's a tech spec manual, meant to be used only by those who already know what they're doing. It needs to be re-designed, re-formatted, re-written from the ground up to be a USER manual... not a tech manual.

Or... if that's not desired, someone needs to start a SECOND Wiki... designed to be a user manual. That is perhaps an equally valid concept. But my question would be: why have two separate Wiki when one would do the job? Keep it Simple, Silly.

Best wishes to all! Kudos Strife, for bringing this to public eye (better late than never). : )

Additional thought:

The EXAMPLES in the Wiki need for the most part to be totally replaced. Most of them are overly complex, don't show the function in daily use, and in many cases aren't even valid as examples.

Yes, the SEARCH function could be replaced with something more valid (why is it a company like Linden Lab can't manage basic SEARCH... search is lousy for ALL of SL)... and the initial LsL access page re-designed to be far more helpful and intuitive. I'm afraid (in my opinion) this is a case of a house where only the foundation and framework is still strong, but the walls, plumbing, electrics, siding, shingles and roof need totally replaced.

Strife has given us the framework. It's all there and was a LOT of work. Beyond that, to make the Wiki truely useful, you need to pretty much rip out what's there and replace it with new things that are a bit more pleasing to the eyes.

OK I'm done. That's about all the time I'm going to have to spend on this subject. Enjoy!

Another example of BAD WIKI:

I wound up with a little extra time, so thought I'd comment on one of the most outstanding examples of "bad Wiki":

THE CURRENT STATE:
Function: llMessageLinked( integer linknum, integer num, string str, key id );

The purpose of this function is to allow scripts in the same object to communicate. It triggers a link_message event with the same parameters num, str, and id in all scripts in the prim(s) described by linknum.


• integer linknum – Link number or a LINK_* flag, controls which prim(s) receive the link_message.
• integer num – Value of the second parameter of the resulting link_message event.
• string str – Value of the third parameter of the resulting link_message event.
• key id – Value of the forth parameter of the resulting link_message event.

**************************

This is a prime example of user-unfriendly technobabble.
If I may respectfully offer:

Concept: llMessageLinked(prim number, any integer, any message, any key or message);

Purpose: To send a message and/or data to one or more prims within a linked object.
SEE ALSO: link_message event (the receiver)

Syntax: llMessageLinked(integer link,integer data,string data,key or string data);
where...
integer link: the link order of the prim in the object
integer data: user-defined data. Can represent any integer number, for any purpose.
string data: user-defined data. Can be any message up to 256(?) characters.
key data: any UUID key. Alternately: a second user-defined message.

Constants which may be used for integer link:
LINK_ROOT - the root prim
LINK_SET - all prims in the object, including the current prim
LINK_ALL_OTHERS - all OTHER prims in the object
LINK_ALL_CHILDREN - all CHILD prims in the object (but not the root)
LINK_THIS - the same prim

Example 1: llMessageLinked(LINK_SET,0,"ENGINE ON",""; // sends to the entire set of prims the message "ENGINE ON"

Example 2: llMessageLinked(5,3,"",llGetOwner()); // sends to prim #5 of the object the numerical value 3 and the UUID of the owner of the object.

USAGE EXAMPLE:

SENDING SCRIPT
default{

touch_start(integer total_number){
llMessageLinked(LINK_SET,1,"FIRE IT UP!","";
}

}

RECEIVING SCRIPT:
default{

link_message(integer sender_num, integer num, string str, key id){
if(num==1 && str=="FIRE IT UP!"{TurnOnEngines();}
}

}

=====================================

That seems to me much more easy to understand. Even a new scripter when reading this, would likely understand how this works.