Wiki Etiquette

[CodeDesignerLab]

I learned LSL years ago mostly using the wiki. After a several-year break, I have come back to the wiki for various reasons. I have noticed, now that I am a much better developer that the examples in the wiki are not the most digestable code. I don't want to put down the original authors as their contributions have helped countless people.

What I want to do is go through and make a lot of minor edits to the wiki and refactor the examples and useful snippets to be more readable and have better comments etc. However, I don't want to step on toes here and upset anyone. I wouldn't change how the code works, just how it is formatted, clearer variable names, and more concise comments.

What is the etiquette surrounding this?

Edited February 29 by CodeDesignerLab

[Perrie Juran]

Perhaps it would be more appropriate to ask this question in the Scripting sub forum.

 

https://community.secondlife.com/forums/forum/304-lsl-scripting/

[Qie Niangao]

Don't fix code samples from Void Singer. They may not be easily digestible but they're worth a good chew.

Otherwise… I'm torn. There's value in seeing a variety of styles. But it isn't the easiest on-ramp for those new to LSL.

[Rolig Loon]

I think you're right to be cautious. Wiki editing can be tricky. We've had some trouble in the past with a couple of people who made changes that I'm sure were honest attempts at improvement but had to be reverted later. As Qie says, please don't edit any of Void's examples. Yes, they can be opaque at times but they are marvels of coding. They are not beginner-level examples but they are great for those who want to explore a compact scripting style. Perhaps the safest way to make the wiki examples more useful would be to add judicious comment lines where they seem helpful.

Unless you already have editing privileges, you'll find that you have to ask LL to grant them to you before you'll be able to change anything. I think they tightened up on that three or four years ago when the last incident of peculiar editing took place.

[elleevelyn]

my advice is not to edit other people's code submissions for stylistic reasons.  Stylistics is subjective, what the writer sees is not necessarily the same as what the reader sees

stylistic is not the same as substantive. Stylistic is used in tutorial materials. Substantive is used in reference materials. While at the same time a wiki typically tries to fit both roles. Another way to think about this is the difference between longhand and shorthand.  In some (if not most) uses of shorthand the reason is that the shorthand version is often substantively more efficient

is best I think to not to attempt to edit/change existing reference material  to tutorials.  Is best to add new code tutorial submissions. Which should typically have the tutorial function embedded in a complete executable script. The student able to copypaste the entire tutorial script and run it

[elleevelyn]

12 minutes ago, Rolig Loon said:

Unless you already have editing privileges, you'll find that you have to ask LL to grant them to you before you'll be able to change anything. I think they tightened up on that three or four years ago when the last incident of peculiar editing took place.

llSay(PUBLIC_CHANNEL, ...) vs llSay(0, ...)

stylistics can make people go nuts sometimes

[Lucia Nightfire]

4 hours ago, CodeDesignerLab said:

What is the etiquette surrounding this?

IMO, you should not edit/delete already posted script examples.

You should post an additional script example below it/them and include either a revision number, iteration number and/or date & time of your example.

Another thing you should refrain from is mentioning that your example is "better" or "supersedes" an already existing example, but you can mention how a certain method/function/scope is faster.

Just, my two pennies.

Edited March 1 by Lucia Nightfire

[Rolig Loon]

9 minutes ago, elleevelyn said:

llSay(PUBLIC_CHANNEL, ...)

was adopted as what was meant to be the wiki standard a dozen years or so in the past. I can't remember who did that and can't see that it has been adopted wholeheartedly. It's a logical suggestion, though, since it's not necessarily obvious to a new LSL scripter that channel 0 is the public channel -- or what that means. Using it in the wiki might make an occasional newbie say "Oh! I didn't know there was anything special about 0."  Anyway, it's a nice example of why even simple wiki editing can be tricky.

[CodeDesignerLab]

I appreciate the feedback from everyone and generally agree with most points so I won't make any edits. 

[Wulfie Reanimator]

When I edit the examples on a wiki page, I add new ones and leave the existing ones on the page. There needs to be a really good reason to delete an example, even if it's one of those really verbose and over-engineered ones for a simple function.

[elleevelyn]

4 hours ago, Wulfie Reanimator said:

When I edit the examples on a wiki page, I add new ones and leave the existing ones on the page. There needs to be a really good reason to delete an example, even if it's one of those really verbose and over-engineered ones for a simple function.

i agree with this approach.  The only time an existing code should be deleted (or reverted after a bad edit) is when there is an actual bug in the code (bug in this case meaning the example doesn't actually do what it purports to do)

editing code can also break (introduce a bug or introduce a behaviour that was not intended by the orginal submitter)

a instance of this came about some years ago due to a convo over the street. The convo lead to discussion about a modification to an existing LSL wiki general purpose method that would make the  matter being discussed be slightly more performant

somebody edited the existing LSL wiki code entry as a result of the discussion, which broke the generality of the LSL wiki method. An edit which had to be reverted. The editor didn't understand that negative zero and positive zero are two different things even tho in most common use instances they equate to the same value