Wiki Wiki Wiki

So just saying that despite the (pardon) opinionated statements of a few people here

* Simplify the syntax as much as possible under the current concept and use terms people readily understand

That's all I got.

/me again declares that she's pretty happy with the wiki and, again, thanks Strife for all his work there.

This is why we luv hedgehogs and ferrets

Ferrets? There's a ferret here??

I know there's Argent the weasel but didn't know there's a ferret..

/me runs like hell.

It is serialized in the process of being sent over the network. Not before or after. It was a pain to find in the code. The actual conversion is done in the code for an implicit typecast that handles converting a llColor4 into a llColor4U. The only reason I had any hint it was in a typecast was that they mentioned a typecast in the comment but the code didn't have one explicitly.

.... he format IS user-unfriendly, regardless of whatever advantages it may have. No, the ideas I presented are not out-of-line or improper; they are used in professional technical manuals world wide and have been for decades. Like I said in the last post... there's often more than one valid way of doing somthing. Your approach is technical. My approach is user-friendly. Guess whose approach in the long run would receive the fewest complaints?

Prajna: So what makes everyone but you opinionated? If your opinion is different then everyone else is opinionated?... I beg your pardon? Simplify the syntax? Do you mean the LSL syntax or does your syntax leave something to be desired?... Jesse didn't misread you. She read you perfectly...If all your previous fond farewells are anything to go by, I bet it isn't.

Nika: I think revising the wikis to be a user-friendly introduction to LSL, as WELL as reference guides, is not well-conceived --- you'll end up with something that makes no-one happy."

I think revising the wikis to be a user-friendly introduction to LSL, as WELL as reference guides, is not well-conceived --- you'll end up with something that makes no-one happy.

And Strife... we're good. I think you just came across a little to strongly in your first return message-- but hey, we've all done that here at one point or another, me included. We all tend to be passionate about this subject.

I understand and sympathize with your stated position on the LsL Wiki. Whatever the community agrees upon as a majority is how the Wiki should be presented. And yes, before any vast changes would be made, people would be needed who are willing to spend the time in making those changes. I will admit I have neither the time nor desire to take on such a project (primarily because Linden Lab should have paid a professional to do it right in the first place... and I'm long past volunteering to do their work for them for free). So you're one-up on me in that department. I devote my volunteer time elsehwere on SL, to the direct support of specific groups. We all play our part both in VR and RL.

So under the current situation I'll simply say this: no, people aren't tarring and feathering you... nor should anyone do so. But there IS a whole lot of grumbling over the difficulty and indecipherability of the current WIKI. The format IS user-unfriendly, regardless of whatever advantages it may have. No, the ideas I presented are not out-of-line or improper; they are used in professional technical manuals world wide and have been for decades. Like I said in the last post... there's often more than one valid way of doing somthing. Your approach is technical. My approach is user-friendly. Guess whose approach in the long run would receive the fewest complaints?

I'll take the disgrutled complaints of a few stubborn techs over the complaints of thousands of frustrated end-users any day. And frankly, under my suggestions even the techs would get used to it and quickly adapt. So just saying that despite the (pardon) opinionated statements of a few people here, the method I've presentd is not insane, not ridiculous, IS industry-standard, is widely used and has been for a very long time. Sorry some folks here prefer deep-tech over usability, but that's their personal preference. Agree or disagree, I respect their right to opinion.

IF you're going to continue under the current format, then I would make the same recommendation others have made:

* Simplify the syntax as much as possible under the current concept and use terms people readily understand

* Organize the system a whole lot better (the clunky and obtuse llSetPrimitiveParams page is a prime example)

* Provide more meaningful data definitions ("the third string in the object parameters list" is not meaningful)

* Provide simplifed and valid examples, and trim the "garbage" from those examples... relegating the escoteric stuff to an external page. We don't need to know how to create and dump a data list in order to be able to send a linked message. That should be handled under list creation and dumping, yes?

* I very much agree with your statement Strife, that something needs to be done to reduce the front-end opacity of the LsL Wiki. It's semi-organized yes, but has zero flow. A first-time (or even long time) visitor is faced with a warehouse of largely arbitrarily-placed infomration without a visible starting place, without logical and immediately perceptible order or path. It's currently kind of a "shotgun effect" page that needs t be more transparent and understandable. It needs to become a "Welcome Island" with logical, perceptible order and flow. For new scripters, currently its downright intimidating.

* I would strongly recommend, as one user mentioned to me today, that you Strife take a back seat position of technical consultant and bring in a writer to do the writing. That is not an insult-- just the opposite. It is acknowledging your signifcant (and frankly amazing) skills as a tech and using those skills where they are best suited. Again: never let a tech write a tech manual. ;D I know of course, finding a qualified writer who's willing to spend the time might be a nigh-impossibility, but it's just a suggestion. Nothing more than feedback.

* At the risk of sounding personal (and forgive me if it does) when new people come to the LsL Wiki all enthusiastic and fired up to help, a little friendly guidance serves a lot better than "supreme coder syndrome". A little less judgemental... more friendy attitude and a humble, guding hand can go a long way toward keeping those enthusiastic volunteers enthusiastic. Remember that just like any newb, they're going to make mistakes, they won't have the whole picture, they'll need to be brought up to speed. Don't be condescending or poo-poo their ideas just because such are not 100% accurate. Remeber that not everyone enjoys the genius of Strife (and I mean that in all sincerity... I wish I had even half your brain power). Rather than being "critical"... be helpful. And remember... that this particular LsLWiki newb was responsible for creation of the concept of "Newbie Notes"-- despite your disagreement with my general manual-writing methods. There's something to be gained from everyone Strife, regardless of their proficiency and expertise (or lack thereof). So don't look down on newbs, even if they make mistakes and "don't get it". Encourage them and guide them instead.

Primarily, above all... KEEP IT SIMPLE. If there is one overwhelming fault of the LsL Wiki... it's never using one small word when twelve big ones will do. It seriously needs to have someone go through the whole thing and turn the technobabble into (yes) plain-english, sensible writing.

That's all I got.

Oh and congratulations are in order, you are now a Devious Wiki Author. Quoting text you help author... the edits you made subtly changing the opening wiki text and just possibly the wiki's mandate...

Chaz: You haven't seen the Mission and Goal statements

Honestly, the function pages as they are should not change. What everyone is asking for should NOT be on those pages other then as links to the information at the bottom

* llSetPrimitiveParams - I'll work on it when I get time. It's a big redesign. The entire way constants are presented in big articles needs to be rethought.

* Part of the problem with providing parameter descriptions is that they are often pretty well described in the general description. I'd like every parameter to be described but I don't want to repeat information, it can be distracting. The only time I see repetition as valuable is when in a subsequent repetition you expand upon it, you add to it.

* Oh someone previously mentioned "idata", thats on the list to get fixed. I don't like badly named parameters.

There is no way to detect automatically if an example needs to be rewritten....
existing examples should be simplified. While on this topic, we need to write better guidelines for examples; I'll put that on the todo list too.

* I don't think I am the right person to write the documentation. I'm not very good at writing code that is to run in the human mind... the manuals people have written on the topic just don't work for me.

Eren you didn't know what you were getting into when you joined the wiki, it wasn't your fault. Things would have gone a lot better if you had known. There is something we need to do when new authors join the LSL Portal, we need to tell them the rules and what they should expect. The assumption that they will find and read the rules doesn't work. If things had been properly spelled out to you, you would have approached the wiki differently. You didn't know the rules and we didn't explain them. My gut says some of the blame is yours but you were new and I was the senior; the expectations of my gut aren't right.

Syntax simplification... I have no problem teaching alternate usages as long as the complete one is prominent.

Chaz: You haven't seen the Mission and Goal statements but you have already noticed the cross purposes.

The Mission Statement is:
"To provide accurate documentation for the scripting language of Second Life: LSL"

The goal is:
"To provide documentation to help scripters of all skill levels."

Mission trumps goal in case of conflict.

Late addendum to a previous point Strife:

A suggestion regarding the prominent part concept, based on an unmodified current format (although as stated previously, even that could be modified for easier readability). Let's use the ever-popular llSetColor as an example:

(bold faced) SYTNAX: llSetColor(vector color,integer face);
CONCEPT: llSetColor(<red,green,blue>,prim side);
EXAMPLE 1: llSetColor(body_shade,3);
EXAMPLE 2: llSetColor(<0,.5,1>,ALL_SIDES);

I would believe that those formats, presented one prominent and the others following, would go a long way toward explaining things for both techs and newbs. I know that myself, looking at this as a first-time coder... I would instantly get the concept and see the format at almost the same glance.

Not saying it HAS to be done this way. There are alternatives. But I believe the above would work-- and work well for most purposes and skill levels.

<.< >.> the proposal sounds good, it might just work.
I suspect there will need to be some changes to the layout to make this work and I'm not sure what those will need to be.
The next step considering this is to make mockup function layouts that are adaptations of the current function layout proposal (on the wiki).

Jesse just triggered and interesting idea for me.

I realize we have an examples section in the template, but maybe instead of just putting illustrative examples, and small helper functions that use or assist them, we could also add links to the library page of much more complex, but relevant examples... this would both feed into providing more examples AND allow Commonly useful and request stuff to linked to where it's most easy to find. no template modification needed. (a great example of this is basic notecard reader scripts tied to the functions heavily involved in their use.. namely the get number of lines and dataserver events (and maybe ever the get inventory functions) (or perhaps use helper functions to provide such a link list)

if we could somehow reciprocate the links we could even sort and categorize the library page links to reflect what functions they serve or highly rely on (as well as identifying unlinked ones so that they might be usefully linked this way also.)

These three need a bit more thinking done. -- That means "Please comment on these"
* Split Issues into Issues and Bugs, put Bugs in Caveats
* JIRA Search link. -- put link next to Issue subsection title?
* See Also-Examples should be moved into Examples section -- Will need better name, any suggestions? Just "See Also" possibly?
* New subsection See Also-Snippets to be moved into Snippets.

/me adds a helpful comment!

There are 4, not 3.

/me adds a not helpful comment!

Possible saw accident? Maybe Strife ran out of fingers?

We already (i'm pretty sure) a Library subsection in the Also section... but it should considering be moved up. An examples-link subsection could be created and put into the Examples section. It sounds like a good idea. Same could be done for Snippets too. That said, a table of links might not be the best solution. We will need to try out different layout solutions.

I'm currently out of town on a borrowed computer so I don't have the ability to do more then chat.