Wiki Wiki Wiki

I personally, find your suggestion worse then what is already there. I like reading a function with the variables it takes first, so I know the format. What just needs to be done is to make those variable names understandable, string str, doesn't say much no, but I think your Concept and Format should be flip flopped. Also new scripters will be very confused on why you have 3 variables of the same name and will be complaining of compiler errors. The main thing for functions that trigger an event is to make sure the function parameters and event parameters match, word for word.

If you use llMessageLinked(integer link, integer num, string data_string, key data_key) you will have to match that exactly with the link_message event: link_message(integer link, integer num, string data_string, key data_key), or you will confused people a lot.

So the hard part of all of this, is to make sure that functions that trigger events have to match the example call.

Lazink, looks like you caught my post in the middle of an edit. Perhaps you'll find the finished product more acceptable. The final format was:

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

This is a simple-English "definition" that tells even inexperienced scripters exactly what may be used in this format. There are no "same" variable names... for there are no variable names here. Variable names have nothing to do with the concept of the function, for the user can use either variable names in this function, or actual data. Thus, "any integer", "any message", "any key or message". That fairly explains to the reader that this is coder-supplied information.

Rather than focusing on the use of "variable names" (which is what you're used to under the current Wiki) it would be better to examine the principles involved. I'm writing a quick suggestion here, not the Wiki itself, so my examples may require further examination. I'm just throwing them out there for consideration.

I appreciate that you personally prefer the format before the concept, and that you like reading a function with the variables first. I respect that as well... for your personal preference. But that's the problem with the current WIKI... a limited number of experienced people insisting on the existing format and what THEY want, rather than being able to see what the SL populace in general NEEDS.

I've even seen comments from some people who think the Wiki is absolutely fine as it is. Despite their personal opinions... they're wrong. The Wiki is obviously not just fine as it is... or Strife wouldn't have seen a need to post this forum thread asking for feedback from the SL populace in general. That populace in general-- doesn't like the current Wiki format.

You're obviously an experienced coder. Obviously, you prefer the tech right up front. But that's one of the major problems with the Wiki. So let me ask you a couple of questions:

Can you still understand and get the information you need, even though the format comes second?

If the entire WIKI followed the idea of concept first, format second, would you still be able to quickly adapt to that and still get the information you need out of the Wiki?

That's the point. I appreciate what you as an individual like and I appreciate that is your opinion and preference. But VERY OBVIOUSLY that is not what the majority of the people who use the Wiki need... because that's how it's done now and they very verbally don't like it.

There's a very good quote on our group website (no personal inferences intended... this is just generalized wisdom):

"Only a fool continues in the same destructive course, expecting the outcome to somehow be different."

People don't like the current Wiki. They have said that over and over, frustrated that no one seems to be listening. In order to change that, the Wiki is going to have to CHANGE, not remain the same.

To expand a little more on this recommended format:

* The CONCEPT line is a one-line, english-based explanation of the general layout of the function

* The PURPOSE line is a one-line (generally) english-based explanation of what the function does.

* The SYNTAX section is an entire section (including variable details) on exactly how the function is used in coding.

Since the SYNTAX section can be quite lengthy... it stands to reason it should follow the brief Concept and Purpose lines.

Agree with Eren. For what it's worth, I vote for: "Say what a function does first, and then the format." Here's why I would vote that way:

If a page in a French grammar book started right off with telling you how to conjugate "aller" in the past-perfect, and only in the middle of the page told you that it means "to go" (while, say, you were looking for something that means "to give"... well, you'll just have read all that conjugation stuff for nothing.

Instead:

Aller
Definition: a verb meaning to go.
Conjugation: (etc)

llMessageLinked
Definition: a function that allows linked prims to communicate with each other.
Format: (etc)

Right away, the general reader knows if s/he is on the right page or not. Experienced people's eyes won't even waste a second on the definition.

Again, part of the stated mandate of the LSL portal (not sure who wrote it): http://wiki.secondlife.com/wiki/LSL_Portal "It is intended to help scripters of all skill levels."

We don't want two official wikis -- one for the 1% of scripters who are pros, and a second one for the 99% (or 97.3 or whatever) of people who aren't or who want to learn.

But right now, I feel the official one could do more to reach out to beginners and learners. To me, it's like making them go to Mass in Latin, because all the Church scholars and priests understand it.

Thanks for illustrating that. That's precisely the point I was trying to make. Your reference to a grammar manual makes that easy to understand.




LOL EXACTLY! LOL.

Further example:

The llMessageLinked() function presents the following as an "example":

// This is just an example script, you shouldn't handle link message within single script this way.

default{ // To propagate an unlimted number of arguments of any type.
// Presumed, the separator string isn't used in any source string!
state_entry() {
list my_list = [1, 2.0, "a string", <1, 2, 3>, <1, 2, 3, 4>, llGetOwner()];
string list_parameter = llDumpList2String(my_list, "|"; // Convert the list to a string
llMessageLinked(LINK_THIS, 0, list_parameter, ""
}

link_message(integer sender_num, integer num, string list_argument, key id) {
list re_list = llParseString2List(list_argument, ["|"], []); // Parse the string back to a list
}
}

*******************
The questions that come immediately to mind are:
If the above shouldn't be handled by a single script in this way, why present it that way?
Is it too difficult to divide this into two valid programs?
Why complex this entire thing up by getting into string parsing and list dumping? What does that have to do with llMessageLinked?

Here's what should have been presented (well, I wouldn't have used this example at ALL...LOL... but retaining this example, here's how it should have appeared):

SENDER PROGRAM:
default{

state_entry() {
list my_list = [1, 2.0, "a string", <1, 2, 3>, <1, 2, 3, 4>, llGetOwner()];
string list_parameter = llDumpList2String(my_list, "|"; // Convert the list to a string
llMessageLinked(LINK_THIS, 0, list_parameter, ""
}
}

RECEIVER PROGRAM:

default{

link_message(integer sender_num, integer num, string list_argument, key id) {
list re_list = llParseString2List(list_argument, ["|"], []); // Parse the string back to a list
}
}

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

So I've covered here just a few issues with the Wiki that need attention... which is what Strife asked for. Accept these suggestions or not, as anyone wishes. But consider:

Do people in general appreciate the Wiki any more today than they did 4 years ago?

So what ya gonna do about that?

Unfortunately, I lost the time and interest in contributing to the Wiki. It required extreme effort and frustration to get anything done at all, and I've moved on to other things.

So it's up to you folks what you do. Are you just going to "stay the course"... or are folks willing to CHANGE to improve it? That's your choice. Me, I'm building a starship.

Thanks strife for the jira todo adds, it was something I meant to add to the discussion page, but forgot untill this thread came up.

if you know whom to get ahold of for <lsl> tag keyword linking, I'd love to talk to them about either making it editable or at least updating the links to the correct pages and including the new stuff too
.

personally I dislike making legacy stuff harder to find, at the same time I can't even tell which of the old limits apply to the legacy prim types, or if some of those limits have been subverted by changes to the handling in the new VM or even by newer viewer limits... and I really haven't had time to test all the permutations of those possible limit changes on prim torture, whether by editor (after you set the legacy type) or by script.

I do agree that including it inline is a little messy though, so count me as ambivalent =/ (although left justification sounds grande!)

@Readability

here here =)


pointless nitpick, it's 255 not 256, the range count is mathematically misleading and will yield inconsistent numbers for pure white (a mistake I recently made and had to correct to yield logical results)

but, I DO like the idea of promoting function over form, it's a lot easier to understand for the uninitiated, but we need a consistent format that isn't going to drive experienced programmers nuts too. that should also jumpstart new users into understand pure tech speak when they come across it =)

another nitpick: 'syntax' is such a user unfriendly word... perhaps 'format' would be a better choice? or usage? (although I feel that's misleading as to be an actual example)

and one final nitpick, user freindly variables should never be abreviated. idata:bad, an_integer:good or even integer_data

personal preference is format first, not just as a code monkey, but as a user. once you've learned the purpose of a function, it's likely you'll only come back to check the format, and that should be the easiest thing to find, i.e. it should be first. (although it is currently instituted as the heading, so that may be a moot point, unless the intent is to change that too, which I'd definitely be opposed to on a personal level.)

I think the word comparison fails in that functions only have one representation, much like nouns in english, so that reading a description before the format is much like a diction that tells you the meaning of a word before it tells you the word or it's spelling. (but is mollified by the header inclusion so...) although I'm not sure why you feel syntax of just the statement would be longer than a description of what it's doing, or even the context (except perhaps in the case of primitive params, but that'd depend on style and actual usage. that'll be a toughie to make user friendly.)

I do understand that the current format is born out efficiency for completing enormous amounts of work from minimal data... Strife has actually done some rather brilliant things in that regard. User Friendliness takes a lot of man hours of individual attention and there aren't all that many being put in currently by the few editors we have on average. such a conversion would require a lot of individual attention to every page, so it's a huge undertaking, and shouldn't be considered lightly.

Well, it's kind of a 6 of one half dozen of other thing. Consider:

64 / 256 = .25
128 / 256 = .5
192 / 256 = .75

So for most figures, dividing by 256 yields correct results. Dividing by 255 would yield off-results. But.. when one gets closer to the ends...

255 / 256=.996 (which technically, is 1, but not quite)

yet 0 / 256 = 0

So all in all, for typical usage, dividing by 256 seems to be sufficient to the need (though in truth, I doubt it matters all that much. Like you say... potAto or potato.



Totally agreed, which is why....



... I actually chose "syntax" over "format". At first I did choose format, but then realized that the standardization for all the coding I've ever come across was the term "syntax". It is a common-English word... so I intentionally chose that over "format" to better acquaint newbs with statndardized computer nomenclature. That said however, "format" is fine with me. I think "syntax" is more standardized and accurate, but either one works.



Agreed. Looks like you too caught me in the middle of an edit. The revised post dropped the idea of "idata" and replaced it with common wording. One trick about writing a GOOD tech manual is that it isn't easy. Almost constant revision until it's just right.



I know that's what I do. When I check the Wiki, I'm looking for the quick info to help me remember how the code is used, not the hard-core tech nitty gritty. So like you point out, having the CONCEPT first provides fast and quick info... with the SYNTAX providing the details if anyone needs it.

The primary thing in making a document user friendly is consistency and use of common-language terms. BUT, if there is a specific-instance battle between the two... then common-language terms should win out. Why? Because the whole purpose of the definition is to be understood. If it's easily understood, the specific wording isn't all that important. It's a common mistake of techs to try and make hard-and-fast rules for every situation. Coding works like that (usually); real life doesn't. That's why the long-known computer saying: "Never let a tech write a tech manual."



That's a particular interest of mine. I bet with a little skill and patience, even llSetPrimitiveParams instructions could be simplified. One thought that hits me is that instead of trying to handle everything together as is done now, that particular function would be better served by breaking it down into separate areas, with complete-statement examples for each instance. It's not like we're going to run out of paper.

Second thoughts on the llSetColor example...

Previously I recommended the following:

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);

But regarding that last line I got to thinking, why do we need this at all? It's unnecessarily cumbersome, techish and user-unfriendly.

I am well aware that tech and those already well acquainted with LsL Scritping might prefer the llSetColor(vector color,integer sides) format. Like Chaz said, what that 1% (or less) of the Second Life population prefers is not what we're going for here. Most of the people on SL don't speak Latin; neither do they speak technoese. llSetColor(<red,green,blue>,sides) is greatly preferrable to most people.

There is no one hard-fast rule that will properly apply to everything to make it READABLE. What works well for one function may need to be literately changed to work properly for another function. Yes, it is less "technical" and less "consistent"... but that's the point isn't it?

It doesn't HAVE to be technical and consistent; it HAS to be accurate and unerstandable. If it's accurate and understandable when read, technical consistency be hanged. That's the difference between a good user manual and a technobabble manual. Sometimes techs insist so much on crossing all the t's and dotting all the i's that they forget that the words they're using don't make any sense. ;D

I know all may not agree with this, and there may be different opinions and different thoughts. But I've been writing user-oriented tech manuals for over 20 years... and I do know what makes manuals readable-- and what makes them overly complex. In order to make a manual readable, one has to think about WHAT the function is doing... not the exacting linguistics of precise technical syntax. Technical syntax simply isn't important. WHAT THE FUNCTION IS DOING and getting that idea across to the reader is what's important. That's a concept that's very difficult for techs to get their heads around... but that is what makes the difference between a good manual and a tear-your-hair-out manual.

I would like to say that the format I've presented above isn't necessarily the ONLY format that would work. I think it's one of the best, but let's take a look at a standardized "reference manual" format for the same functions presented prior:

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

Alternative:
llMessageLinked(integer1,integer2,string1,key or string2);
where all data is sent to the receiving script...
integer1: the link number of the prim or a CONSTANT (see following)
integer2: user-supplied data (may represent anything)
string1: user-supplied message up to 256 characters
key: user-supplied UUID or...
string2: user-supplied second message
(CONSTANT information here)

This syntax is very ACCURATE yet still understandable... especially if followed up by the plain-English defining section as shown above.

That is standard, by-the-book reference manual syntax... and it's still readable and understandable-- especially once the examples are given.

The same applied to the llSetColor function:

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

Alternative:
llSetColor(<float1,float2,float3>,integer4);
where...
float1: red value from 0 to 1
float2: green value from 0 to 1
float3: blue value from 0 to 1
integer: side of the prim to color, or the constant ALL_SIDES

When one thinks about it, any of these would work. I personally think that:
llSetColor(<red,green,blue>,sides)
is far more readable and understandable. I just wanted to point out that there is more than one way to make a totally readable Wiki that most people can easily understand.

But what makes zero sense to most beginning scripters from a syntax standpoint is:

llSetColor(vector color,integer face);

comparatively:
llSetColor(<float1,float2,float3>,integer);
is significantly more readable and infomative, while still retaining consistent syntax.

The fact that it's a VECTOR really has zero importance to the function of the script. So long as users follow the syntax and include the <>... the actual word "vector" is totally unnecessary to the concept or syntax of the script... and just makes things more confusing to beginning coders.

So to sink the point (and I think this should sink it about as deep as I can without running this all way into the ground)... which of the following would be more readable to all coders in general, both beginning and experienced?

llSetColor(vector color, integer face);

llSetColor(<float1,float2,float3>,integer);

llSetColor(<red,green,blue>,side);

Please, don't look at these according to what we're USED to seeing on the Wiki. Step back and try to view these from the stand point of a new coder, the everyday coder, those who aren't neck-deep in daily coding and who need to refer to the Wiki often to refresh themselves on function syntax. Which of these is going to best get the idea across, the USEABLE syntax across, without decoding concepts such as "vectors"?

Which of the following llMessageLinked definition sections is more readable and understandable?

=====================
• 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.

=====================
where all data is sent to the link_message event...
integer1: the link number of the prim or a CONSTANT
integer2: user-supplied data (may represent anything)
string1: user-supplied message up to 256 characters
key: user-supplied UUID or...
string2: user-supplied second message

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

This is just feedback, as requested. Not telling anyone how they have to do anything. It's your baby; you choose.

I prefer the first one, because I prefer the llSetColor wiki page to be a reference, not a page on LSL in general.

LSL is a language (and a library of functions), and is built up from smaller parts. If a person looks up llSetColor, and doesn't understand what a "vector" or "face" is, they should click on vector or face to learn that first. Then hit the back button to see it used in context.

If every function page on the wiki must act as a reference AND a guide to learning the language, the entire wiki will become too bloated. Build the wiki with hyperlinks, as it is meant to be used.

I disagree. The first choice is written for computer scientists. A non-techie shouldn't have to leap through a half dozen preliminary links to get every term defined in order to see what a function does and what sort of information it requires and produces. It's certainly important in the long run for anyone serious about scripting to know the underlying basics, but it's counterproductive to put so many hurdles in the path to learning that a self-guided student is paralyzed.

I consider myself a reasonably intelligent person with a couple of advanced degrees, but I'm a non-professional scripter. I rely heavily on the wiki (and the MANY helpful people in this forum ), but navigating the wiki to get a straightforward understanding of an unfamiliar function is like trying to do my taxes with the IRS forms ("Insert 0.029 x the number you entered on form 1086, Line 27, unless your gross income (minus credits) was more than $50,000 or you reported a loss on Line 45 of form 1173B.......".

Give me the third option and put the links for further information in the supporting text below it.

I prefer the third one. I believe that the wiki should also be a learning guide, to address better part of its declared mandate of being for all levels of users. I don't believe that being accessible equals bloat. If I'm starting out and want to set a colour, I shouldn't have to follow a link to a treatise on the history of vectors. A link should be provided for further reading -- but I should be able to tackle that at a later time but in the meanwhile get on with the task at hand so I don't give up in frustration.

Agreed. Or like a Martha Stewart recipe whose ingredients are sub-recipes each requiring 2 hours of work on their own :} .... 2 tablespoons of "Sauce Béarnaise" (see page 79), 1 tablespoon carmelized onion (see page 397)..... LOL.

The way the wiki is laid out now it fairly standard for a programming reference, it's really not a departure from man pages or all the other references that follow the same general style.

The comment above about Martha Stewart made me think that something like that could be what's really wanted, a separate series of "how do I do xyz?" pages rather than something that tries to shoehorn it into descriptions of functions. There can be 3 different functions that do the same job, and most problems will need more than one function to solve, and example scripts alone don't necessarily cover "why do it that way?"

but if you're using 256, then *1* is your starting color
because your range count is 256 shades not 257
but web and computer colors range from 0-255 so your quarters actually fall on 0/63/127/191/255 not 0/64/128/192/256 (which is a ranging error)

  0 / 255 = 0.0000000 * 255 = 0.000000
  1 / 255 = 0.0039216 * 255 = 1.000008
127 / 255 = 0.4980392 * 255 = 126.999996
128 / 255 = 0.5019608 * 255 = 128.000004
255 / 255 = 1.0000000 * 255 = 255.000000
internal margin of error +/- 0.0019608
external margin of error +/- 0.0000080

  0 / 256 = 0.0000000 * 256 = 0.0000000
  1 / 256 = 0.0039063 * 256 = 1.0000128
127 / 256 = 0.4960938 * 256 = 127.0000128
128 / 256 = 0.5000000 * 256 = 128.0000000
255 / 256 = 0.9960938 * 256 = 255.0000128
            1.0000000 * 256 = 256.0000000 ( oops )
Internal Error Margin -0.0039062
External Margin of error +/-[0.0000128] + ranging error of 257 colors (0 - 256)

result
256 yields error margins of [~2x internally | 1.6x externally] compared to 255
AND it yields ranging errors, either accepting or producing invalid results (#256)

combined you'll notice on conversion of 256_in, using 255_out that you'll either get 2 values for 0 (Floor), or for 127 (cast), or for 128 (round) or for 255 (ceiling) further illustrating the ranging issue

256 is a range count, but since we aren't counting the range, only applying it, 255 is what we want. or to Illustrate as a set [0, 255] (255possible integers) vs [0, 256](256 possible integers)

Notes:
unfortunately the 'brilliant' minds at LL chose to convert standard integer colors to float colors (why I have no clue, less accurate, takes more conversion time/space, and takes up the same space as separate integers )
surely
(integer)color.x
has to be faster than
(integer)(color.x * 255)

That's sort of what the forum and the Scripting Library provides, although not in a way that is easily searchable. I frequently stumble over a script in a post and then find some clever approach that is incidental to the problem at hand but potentially VERY useful for something else. (Example: The thread this week in which Void used (!~x) and then explained nicely why it is the same as (-1 != x), only faster.) I'd never be able to locate things like that with a search, so I have had to bookmark them and create my own filing system. A Martha Stewart cookbook full of those annotated snippets could be quite handy as an adjunct to the wiki.

and once I update the wiki page(s) for operators that info WILL be available via the Portal (speed and size information will go in the notes section for each operator/variableType combination when it's a relevant improvement. some of these optimizations either don't apply to mono, or can't be tested reliably, I'm working on more reliable testing for mono (although they need to fix get free memory for it first for some of it)

So, at the end of the day, who will decide if there are changes to the official wiki or not? Who, in effect and for all intents and purposes, is the boss of it?

I am perhaps one of your target audience. I have been learning LSL as a new language for the last year or two, and the third example is best for people like me. I've been coding for 20+ years, but LSL has been a challenging hurdle because it deals with things I've never needed to know before. In the above example, I can grasp the concept of "red" more immediately than the concept of "vector" -- simply because "vector" requires a second-level abstraction that takes a split second for a newcomer to link to mentally. The brief time it takes to make that mental lookup interferes briefly with the learning process. Of course, after a very short time, "vector" becomes integrated into the learner's language model and the interruption goes away after that. But for new learners, the second-level mental lookup is a small disruption that could be avoided. And avoiding anything that disrupts concentration is a good thing.

So, "red" allows the new learner to immediately grasp the concept of what's needed. After the concept is understood, the next thing the learner sees are notes about what "red" is: it's part of a vector, which is represented by floats. That order of presentation builds on the knowledge that was grasped immediately before it. Learning becomes intuitive, and follows naturally.

I have to agree with everything Eren says, and the best programming manuals I've read were arranged similarly. Give the concept first, followed by the details. I would like to see all variables names as descriptions of what they are. I like names like "red" and "prim_side". Those are immediately understandable to anyone, and the syntax becomes self-documenting. I do not like names like "idata", again, because of the brief internal lookup that has to happen to make the mental association with what's required. Why should I have to decipher "idata" when "integer_value" is immediately clear and flows naturally like human language?

Using "red" and "integer_value" should not be any harder for experienced users to work with, and opens an inviting door to new learners. I used to know someone who sprinkled his code with all sorts of cryptic variable names. I never knew if he did it to make it harder for others to read his work, or because he thought it made him look smarter. In any case, I just thought it was stupid. Code should be as self-documenting as possible.

BTW, I think "syntax" is a readily understandable word, used in not only coding and grammar references but also in common parlance. I like it because I think it expresses exactly what is meant. But maybe that's just me.

"The Community"

One really brief comment because I'm crunched on time right now, then will tackle the rest later.

"Who will decide?"
"The community."

And here is where the concept of the LsL Wiki being a WIKI is a real problem. Because as we've seen above, there is a clear cut line of experienced vs inexperienced... and the tendency of a Wiki is for "Wiki bullies" to enforce their opinions on everyone else (witness the Wikipedia as a prime example).

I experienced that myself on the LsL Wiki. Every "change" or "suggestion" that I've put in the LsLWiki was taken over and hijacked by someone who thought they knew how to do it better. Eventualy, I just stopped contributing and moved on to other things. To this day, I have ceased to attempt to contribute to the Wiki... as have many others.

A REFERENCE MANUAL is ill-served by the concept of a WIKI. It should be constructed by a team of authorized, qualified people, with a public "suggestions" page (or forum) for the general populace to contribute their thoughts. Those thoughts are examined by the committed and incorporated into the manual as they are proved beneficial. That committee doesn't necessarily have to be experienced scripters. It can consist of scripting newbs for the purpose of saying, "That doesn't make sense yet."

Otherwise, all we wind up with are "wiki wars" with prideful tech-types taking over, and everyone else throwing up their hands in disgust (well, pretty much as it is now).

That's all I have for right now. Will address other points and the "what is best" debate later when my event is done.

Great comments on both sides btw. I belive the "keep it as it is" folks are dead wrong (which should be obvious by the large number of long-standing continuing complaints regarding the LsL Wiki), but they're good comments nevertheless.

fixed.

because, when it comes down to it, the editors have to do the work. if an editor doesn't do the work, it doesn't get done.

but anyone can offer their opinion to the editors and any SL member can BECOME an editor if they so choose. (it's NOT limited to payment verified's like the forums)

personally I defer to those that do the most editing, because they put in the most work. so it falls to them to implement changes more than I.

Personal prefernce noted and respected. Yes, that meets your needs. But how about the needs of others who aren't as well acquainted with scripting?

I would disagree that the wiki would be "bloated" by using simple standard reference manual design methods (the current LsL Wiki does not, and IMO is somewhat bloated. Just look at the llSetPrimitiveParams page for an example).



Hyperlinks are great if they're used right. Using them every second word and in place of common-sense language causes them to lose their value.



I was tempted to quote your entire post... because it's right on the button. In regard to your last comment, you're exactly right. Hyperlinks could be easily and properly used to take people to additional support pages where further details can be provided... as extensive and techish as any tech may like. The main page should be useful to all levels of coders, not just the highly-experienced "IRS agents". ;D



Precisely. The Wiki is not just for use by those who already know what's going on to use as their personal-comfort-level reference manual. It needs to be accessible and understandable to ALL levels of coders... including beginners.



Yups. Writing in simple, understandable terms does not equate with "bloat". The goal of this particular manual should be to provide the information required in an easy-to-understand format. There is currently a high degree of "frustration" involved with the current LsL Wiki... the primary reason being it's simply not designed and written in a user-friendly manner. It's a tech manual, written by techs, for techs... and leaves everyone else out. Frankly, I don't even consider it to be a good tech manual. The repeated references to obscure concepts and excessive use of hyperlinks is indeed, "frustrating"... even to techs. Some hyper-geeks may get it and thrive in that atmosphere. Most people don't.



I'll have to disagree on this one. Imo, most BAD reference manuals are written this way. The GOOD ones are written quite differently. Again, a prime example:

BAD:
llSetColor(vector color, integer face);

DECENT (the industry standard):
llSetColor(<float1,float2,float3>,integer);

GOOD:
llSetColor(<red,green,blue>,prim face);

ALTERNATIVE GOOD:
llSetColor(<fRed,fGreen,fBlue>,iPrimside);

That last alternative is something I haven't discussed yet, the often-used nomenclature of setting a standardized, widely-understood TYPE abbreviation to the beginning of every value:
i_ = integer
f_ = float
k_ = key
s_ = string
etc etc.

This is an industry standard, widely-used method of meeting both needs, that of the tech and that of the casual user... and might even be the best way to go.

However, myself, my own personal opinion after over 2 decades of comparing and WRITING tech manuals, prefer:
llSetColor(<red,green,blue>,prim side);
where...
red: float RGB color value ranging from 0 to 1
green: float RGB color value ranging from 0 to 1
blue: float RGB color value ranging from 0 to 1
prim side: integer representing the face of the prim to be colored, or the constant ALL_SIDES

To me, in my experience, this last option provides maximum information with minimum hassle. In truth, the "llSetColor(vector color, integer face)" isn't really needed at all when such listings are employed. The listing as shown presents both the concept and syntax in one, easy-to-understand line and is VERY accurate.

etc etc etc

With all respect void, I believe illustrated in your entire post is one of the major problems of most techs and the wiki itself... not seeing the forest for examining the bark on a single tree.

Yes, everything you say is technically correct (at least, as far as I can tell in that mess. LOL. No insult intended). However, that has nothing to do with the common, everyday user accessing the llSetColor function. The realistic fact is that if 64 / 256 = .25 and 128 / 256 = .50 and 192 / 256 = .75.. that is EXACTLY the results that the vast majority of coders are looking for. They have no desire whatsoever to divide 128 by 255 and come out with .5019607.

That is why techs should not write user manuals. They always cross the Ts and dot the i's... even when doing so is to the disadvantage of the end user. The ones who write the good manuals know there is an art to doing so... and realize there times when absolute, hard-core precise tech takes absolute second-place to getting the job done to the satisfaction of everyone. So I stick by my original post: divide by 256, not 255. That will achieve the results desired by 99.999% of the users. The other .001% can divide by 255 if they so desire. No need to burden down everyone else with such techno-masochistic tendences. ;D



I will surely agree with you there. I'm pretty sure I know why though: to save themselves time and effort on the front-end coding rather than save their customers millions of man-hours later on. Such self-serving "lazy coder" attitude is rampant throughout Second Life... and is especially visible in the layout and design of LsL. Even Cory (the creator of LsL) later admitted the language was a rushed hack-job that he would never again repeat.



Well Chaz, I hate to be negative, but I am going to be totally truthful here: based on the last 4 years experience, I'd predict that despite all this discussion, the LsL Wiki is going to continue to remain pretty much as it is without much in the way of significant improvement... because the folks in charge of the Wiki like it the way it is. The last four years have proved that no one is really willing to listen to the 99.9% of the people on SL who DON'T like it. Because believe it: people have been complaining about the Wiki for a long time... and it's still just as bad as it's always been (possibly even worse).

As I stated before, these types of documents tend to be taken over by the deep core techs... who will then proceed to hijack any effort by anyone else to change that format to something better. Two years from now we'll likely still be having the same discussion... yet again. (That is, if LL is even still around in 2 years).

I've worked in the corporate environment long enough to know that the only way to fix something like this is to change the people involved with it (or alternately, set up a new manager with the authority to implement required changes). Since that's not going to happen, I don't foresee any amazing changes in the layout-- or user-friendliness-- of the LsL Wiki. Not being negative; being realistic. That's why I don't contribute to the Wiki. In my book: lost cause. Right now, about the only person with the authority to change the Wiki for the better-- is Strife himself. With all due respect, that hasn't happened yet... so I'm not holding my breath.



Exactly Paladin. That puts it in a nutshell. Somewhere back there someone got it in his head that the LsL Wiki is supposed to be a tech-reference manual rather than a tech-user manual. They have refused to let go of that tunnel-vision concept and the Wiki has suffered as a result (as have new scripters grid-wide for years). And again, IMO, even as a tech-reference manual, it's just simply not very well designed and written. The point you made about even professional coders scratching their heads is very valid. The LsL Wiki needs to approach this subject as if every scripter reading it is new to LsL, while at the same time presenting the precise information needed for the experts to use it well. I think the format we presented above can adequately do that.



Thanks Paladin. I was hoping someone would verify that. All a person has to do is go to any bookstore, sit down with about a dozen books, and they can read manuals ranging from excellent to horrid. The excellent ones use the format I presented above. "The whole purpose of language is to be understood." Clue to the book industry: the horrid ones don't sell all that well and wind up on the $2.95 discount rack a year later. The good ones continue to sell for years.



Exactly. Self-documenting syntax is the whole idea.



Yes... but will their edits stay in place? And can they change an unfriendly basic format? Answer is no... and no.



You're right there, especially in regard to a "reference-manual" Wiki (really, that is such a bad idea... LOL). The trick of course, is for the editors to be actual EDITORS... and not deep-core non-writing-skilled techs in the position of "editor". There's a big difference between an actual editor, and someone thrust in that position (believe me, I've seen the later time and time again over my career). I'm not slighting Strife and the others or putting them down. But Strife asked for feedback. This would probably be my most beneficial suggestion: step down from the editing postion, put someone in charge of it who knows how to edit it from a PEOPLE standpoint... and provide the tech expertise to make it all work. Get a good, qualified editor in there, change it to a non-wiki format, and the LsL USER GUIDE might be a winner.

Yeah, that pretty much sums up my suggestion. Turn it from a WIKI into a hyperlinked, properly-edited user guide. Unless that is done... I don't really see it improving-- unless of course, Strife decides himself to totally revamp the Wiki. Because to be truthful, he's done a pretty good job at seeing to it the Wiki remained consistent-- regardless of good/bad of the existing format. So he's a pretty good MANAGER of the Wiki. It just needs a new format. Better though, that format be completely changed from a WIKI format to a user-suggestion-box-fueled, professionally edited online manual designed for use by everyone, not just the techs.

That's about all I have for now. Interesting discussion. Back to other tasks.