Wiki Wiki Wiki

... whatever that means. What's a firebug? Related to a lightningfly?

span tags will basically be a label around the section from an included template (ie something included from a different page) so you'll know where it came from.

very helpful since I had a similar problem as you did trying to figure out where certain things were coming from (like how odd entries got into the category pages... it's because the entry being linked to included it as a category on it's page)

firebug is a FF plugin that allows live inspection, editing, monitoring of a page (hey does that have wiki integration? seems like it does what netscape did for source viewing, but editing would only be local?)

Thanks, Void! Ignore all those pesky people who say "Void is nothing!"

On the wiki I use it mostly to test out new inline CSS (much faster then using edit preview). But elsewhere I use it for inspecting the structure of pages when writing GM scripts, Adblock rules and Autopager rules.

I don't know if people know but I wrote a GM script that improves the syntax highlighter on the wiki. It works on both the LSL Portal and the LSLWiki.

http://userscripts.org/scripts/show/28162

Oh I was walking home from work thinking about llGetLinkKey and the awkward wording of it's description. The problem was that the wording "Returns a(n) X ..." made things difficult because when you get to the "..." the "a(n)" makes it one of many, and for things like llGetLinkKey you have to then word it carefully to strip away that many. So I've added support for "Returns the X ...", now I'm also thinking about adding a qualifier before "X" so that it would be "Returns the Q X..." but I'm worried about changing the layout that much.

The wording is how it is so that the type is always the third word but that need not be the case, i'd like to keep it close to the front though.

Actually Strife, this is one of the listings where the description makes sense. To quote:

"Returns the key of the linked prim link_number"

That's fairly understandable. To make it even simpler though to most folks: "Returns the key of the specified prim".

This may be a case of trying to overthink the need. This is one of those cases where the actual syntax of the function is fairly self-explanatory in the name itself: you could probably just use "llGetLinkKey" without a description and people would still understand what it does. So a short, simple, uncomplicated description in this particular case works fine. In truth, from what I've seen, that particular Wiki page is an extraoridinary example of well-written documentation in the Wiki. The Caveat section makes sure newbs don't make logic mistakes. The example is lengthy (and perhaps overly complex) but is thorough (might simplify it down a touch). Overall, pretty decent page.

I was actually thinking about using (something very similar to) "Returns the key of the specified prim" but it didn't make it apparent we were talking about Links. For a new user they may not know anything about Links and how objects are put together. Having a link (to an article on Links) in the summary gives them access to more information.

llGetLinkKey is really just a discussion point (we could pick on a different article).

I'm wondering what everyone thinks about the description method of dropping the technical information in the sentences in parentheses (or in between commas which is the correct way of doing it in English).

Returns the key of specified linked prim (link_number).
Returns the key of specified linked prim, link_number.

In simple summaries you are correct you could drop the variable but the idea of the summary is to describe the function with it's variables. At the end of the day the user has to be able know not just what the black box is but where each lever on the black box is, what they do, and how they work with each other; part of that is knowing which lever is which. But I'm not saying anything that isn't already know.

----

But you should have seen it before I took an ax to it.
"Returns a key which is the key of the prim that is link number linknum in the current link set."
Someone was kind enough to point out that it was "cobbled together" which got me thinking about what the article should be (instead of looking for ways of tweaking it).

I do agree that the example given is too long. It's a systemic problem and should be something that a change to the style should discourage (I am currently unsure what that should be).

Eren, are there any good books (or other resources) on writing documentation you would recommend? I've got theory bouncing around in my head and I'd like to get learn how others think about it.

Returns the key of a prim in the same object, selected by link_number. Or "specified by".

sheesh...
returns the key of the specified linked prim.
link_number should already described as the specifier, so you could probably just drop the word 'specified' altogether, or change it to 'targeted' or 'selected' (since in can use LINK_* targets)

Well, you could also have:

Returns the key of a prim in the same object.

Parameters: link_number: link number of the prim.

See also: [[llGetNumberOfLinks]], [[links]], [[keys]].

I agree.

I like either of the following suggestions:

Void: returns the key of the specified linked prim.

Argent: Returns the key of a prim in the same object.

There are advantages to each of these. Void covers everthing in one simple sentence... including the fact that it's addressing a linked prim. Argent recognizes that anyone who is scripting already knows what linking is... and cuts it down to even more basic concepts: it's contacting a prim in the same object. Personally, in this case I prefer Argent's because it's the simpler-worded of the two and still gets the idea across. But both are equally valid; either one would do very well. One advantage of both is that neither one requires commas or parenthesis-- simplifying the structure of the definition. The less clutter, the better.

To some, this wording discussion may seem like splitting hairs, but imo this is exactly the kind of consideration that would be admirable in this project. It takes time now... but the long-term reward is a technical reference manual that is still understandable to introductory scripters. Every function that we discuss like this and that results in a more user-friendly section of the Wiki... is one step closer to a totally user-friendly Wiki. Since the object is to have an understandable Wiki that doesn't frustrate the techs with endless trivia... this is time well spent.

From another thread here in this forum, it'd be nice if the various llCalls said if they cause a full or partial update (or no update).

Easy (but tedious) enough to test, I guess. Any idea how often LL changes this stuff? Doesn't seem like it would be often but I really have no idea..

If Linden Labs was optimizing the stream properly, you'd have no way of knowing, it would change from server to server, object to object, incident to incident, depending on how long it had been since that prim sent a full update to that client, what the server's load was, what the optimizations in that version of the server were, and so on.

True.

And do you think that's likely to happen soon?

Fnord.

I suppose we could add link(s) to the packet articles that do the actual brunt work. Sounds like something best stuffed into DeepNotes.

I'm deploying some of the changes to the function template, you won't see much in the way of changes, I expect more are coming after I get some sleep and reread this thread.

Here's what is new:
* Bug presence indicator is now an icon, right now the link leads to the wrong area, that's going to be fixed when I tweak the Issues Template.
* Bugs section in Caveats (won't be visible until the above is fixed)
* Link in Caveats that performs a Jira Search based on the function name (and some optional keywords ^_^
* Two New link subsections in examples:
** Simple Examples (varimple-examples)
** Complex Examples (var:complex-examples)
* Messaging subsection in deepnotes, for describing how function calls are put into action at the protocol level. Specifically detailing which packets are sent and when. (var:messaging)

The idea of Complex Examples is to move all of the complex examples out of the articles and use that space for less complex examples. The old examples link section has not been moved up, it is being deprecated (so that people will move the links up into the appropriate simple/complex subsection). We have two types of examples, those that show how to use the function, and those that use the function to design nuclear reactors.

I like the idea of separating complex examples from simple ones. Good simple examples should demonstrate the concept, using valid LSL, avoiding distracting details. Complex examples are useful to convey those details that become important once you've grasped the concept.

Frankly, I think we can dispense with nuclear reactor examples.

Thanks for all your work on this, Strife!

hmmm considering that most examples are currently of the simple variety, why not just default that to the same section, and encourage editors to move the few that belong in the complex section? the lack of visual difference otherwise (and the fact that the new fields aren't in the current page templates as saved) may leave occasional editors confused, and default to using the deprecated section, while not knowing about the newer one.

I'm thinking about going through all the articles (using a script) and inserting the most useful of the missing parameters. You would be surprised at how many there are, and how they might be useful... I also need to update the documentation. I'll also cleanup the arrangement of the variables at the same time, I don't like how they have gotten disorganized.

I would say that half the examples are too complex... but that is just me.

I certainly won't argue with you there. I must confess, I haven't read this entire thread, and maybe all of this has already been said, but I would like to see simple but complete examples of scripts using whatever function is being discussed.

Far too often I see things like snippets of scripts containing the subject, or even more frustrating, statements admonishing me NOT to do THIS, but no example of the correct way to do it by contrast. At my level of scripting, far too often these might as well say "while using this function, take care not to garandarang the sneeble," leaving me to wonder what a sneeble is, and if I might have already garandaranged it, and if this is why my script is not working. This, of course, leads me off on another search.

Regarding examples being too complex, today I was trying to do something with a timer. I searched "timer" and one of the items that popped up was "Timer Module." So, I looked at it, and my eyes glazed over. Nearly literally, as the script font was much too small for these old eyes. Fortunately I was pretty sure that what I was trying to do could be accomplished with about 98% fewer lines. I spent about another half-hour scouring the wiki, then finally gave up and posted the non-working script I'd come up with here, and someone fixed it for me in a few minutes.

I would really like to be able to go to the wiki and figure out how to do things, and I still go look, and occasionally it helps, but more often it only frustrates. And I really hate to have to ask for help, when I know the information is out there, if I could only find it.

I know you started this thread because you want to fix things like this, and this is not an attack. I know you work hard at it, and I appreciate your efforts. I just wanted to communicate some of the frustrations I experienced just today, in the hope that this might help you.