Wiki Wiki Wiki

I think leaving also to also functions etc would make sense... we just need to add those links for similar and related functions etc into there... which is a manual add thing unfortunately.

I've been pounding away at the layout to fit stuff in... give it a look:
https://wiki.secondlife.com/wiki/User:Strife_Onizuka/LSL_Style

Here are the changes I've put in it:
*Caveats has been renamed to "Be Aware"
*Active bugs list in the "Be Aware" section
*Examples, Snippets and Notes each have a More Articles list.
*Renamed the top section from Description to Summary (only shows this name in the TOC)
*JIRA bug and issue searches, link on the right of the section title line (assuming you browser supports inline-block).
* Prerequisite tutorial(s)

It doesn't have any of the controversial stuff, I haven't figured out a way to do that.

*very kewl* feature at the top -- Prerequisite Tutorials: LSL 101: The Wikibook @ Chapter 3

very, very kewl.

I'm not actually happy with the style of the box... same with the LSL Header. The Help Portal Header is so cool it makes the LSL Portal header look lame.

But I don't have any ideas on how to make it better...

I'd like to add some style to all of the boxes, make it snazzy.

in that format, what exactly is going into the notes section? also did you mean to reproduce jira stuff in the deep notes?

(actually feature suggestions is a neat thing to put there, though I'm not sure how populous we can make that considering most if not all of those will have to be added by hand.)

also exactly what is going into specs? will that be a further breakdown of it's parts (like for extended function such as set prim params?)

OOC what is complexity? (and can we later extend that micro list to include byte size? assuming that doesn't change by context, haven't tested that far yet))

Take a look at: https://wiki.secondlife.com/wiki/llEmail
It should answer some of your questions... I hope.

It's not a duplication... well I haven't quite decided on that really. The table in "Be Aware" is only going to contain open bugs. The table in Deep Notes can contain active and closed bugs and feature suggestion. If the list gets too long we'll just trim them off.

Spec is an already existing section, most articles don't make use of it. It's more technical than notes but too long to fit in Summary.

Here is another example of the Spec section in action:
https://wiki.secondlife.com/wiki/llList2String

complexity? It's an optional like Spec, if you don't supply it it disappears. It's not a new feature. Take a function like llListSort. A coder might want to know how long it's going to take, llListSort is O(N^2). As it turns out, there isn't reliable information for most of the functions. When it was added we were still dealing with LSO and it turned out that LSO was slower then the functions.

As to adding byte size? Not all that useful. All function calls are pretty much equivalent. The only real difference comes from parameters... which goes without saying. Additionally, that should really be noted in the LSO/Mono note subsections of Deep Notes because it depends upon the VM.

Another good article:
https://wiki.secondlife.com/wiki/llListSort

Caveat really was the right word, "Be Aware" is just a clumsy phrase that means something similar. so I don't really understand the rational for changing it.

"Prefer the Saxon word to the Romance." -- H.W. Fowler (1858–1933). The King’s English, 2nd ed. 1908. Chapter I. Vocabulary. Section 5.

"Be Aware" doesn't really have the same shape in my mind. I prefer Caveat myself. That one may just get pushed onto the back burner. Caveat is something that is enigmatic to people without an education in Latin, which is good, they may actually read the section and decide that it is important for them. So often we ignore warnings... if we dress them up maybe they won't. But I'm just rambling now. There wasn't enough push for the change anyhow I thought I'd just try it out.

I can't understand what is wrong with caveat either. Is it just because people can't pronounce it? It is three syllables (cav e at) and should rhyme with have me cat. It seemed most appropriate to me.

Are you saying you are depreciating the See Also section? I find it most useful to see a list of related or similar functions.

Was just a thought that occurred to the brain of someone who had been up for too many hours. The See Also section is here to stay... but might be renamed "Related" if people like that instead.

I think you have been up too many hours, Strife Not being a stick-in-the-mud, but people are used to See Also too and I see no good reason to change it.

warning might also be feasible ( the argument against caveat is that it's mostly only found in academia and corporate circles, not familiar to the general populous). gotchas, potential problems, quirks, and several other words are more accessible to a wider audience.

@Format stuff:
thanks for the clarification =)

Warnings? Limitations?

Thesaurus lookup, Caveat: admonition, alarm, caution, commonition, forewarning, monition, sign

Forewarnings may be the best word if you want a direct synonym.

I think 'caveat' is pretty industry-standard for this sorta thing.. Consider me a vote for leaving it as that.

Maybe somebody working on the tutorial/wikibook bits can add a mention of what caveat usually means in this context?

Caution is good.

just the word I was looking for

echo. Really? I didn't know it was uncommon. Perhaps it is less so in other countries. So, yes, if that is the case we could use something else.

Arrgh.. please not "admonition, alarm, commonition, forewarning, monition or sign"

Caution is good. Thanks Argent

That actually looks pretty good. Lower on the page there may still be opportunity to simplify, but the top half looks like it will work fine. : )

Regarding Caveat:

This is a commonly used term, but some folks may not understand what it refers to. I'm sure they'd figure it out quickly. "Cautions" would work as well perhaps, or even "Things to Watch Out For" (sometimes a short sentence serves the purpose better than a single term). Kudos for considering whether Caveat is best or not. Imo any one of these you choose should do ok.

I'm trying to free up some time Strife, to try to help a bit with working up some definition examples. We've been opening 4 new sims so I've been up to my ear fins in alligators, but I'll see what I can put together asap.

How about "Premonitions and portents"?

That's what I said when I saw it in the list.

Might well prove apposite, Argent.

Or a simple "BEWARE!"