LSL functionality rating
This is just a proposal, nothing has been implemented at this time.
Please comment on the discussion page or in the forum thread:
http://community.secondlife.com/t5/LSL-Scripting/RFC-LSL-Documentation-Rating-System/td-p/1392455
Project
The goal of this project is to improve the LSL documentation by providing a sane rating system for articles. The rating system will express how hard it is to master and use the functionality. It is not intended to rate the quality of the documentation (which should be self evident). Secondary goals of this project are to provide a gauge for which articles need improvement and categorize them by their rating.
Articles like llSetPrimitiveParams present a challenge. It is not terribly difficult to master but it is fussy and so complex that it is difficult to use without constantly referring to the documentation. This illustrates that there are two aspects to this: difficulty and complexity. This is something we would like to capture and not confuse but is going to be beyond the scope of this project. Beyond the base functionality and the caveats, an additional modifier are bugs. Many topics have "important issues" that modify how difficult it is to master the functionality, some are obscure edge cases, others are huge functionality changes or deficiencies.
Proposal
In the summary right hover info box, add a rating field to all articles. Add a new section (subsection?) detailing how the topic is difficult.
Articles that are not rated for now will show no rating at all.
Rating Map
| Points | Rating | Description |
|---|---|---|
| [0, 2) | Easy | Like falling off a log, why does this article even exist? |
| [2, 5) | Tricky | Mostly obvious but the examples make everything plain. |
| [5, 8) | Hard | You need to actually read the article. You will regret not reading the caveats section. |
| [8, 12) | Expert | You need to read this article more than once and try out the examples. |
| [12, 20) | Guru | You will want to refer to the documentation periodically to refresh your memory. Which is probably every time you use it. |
| [20, ∞) | Perverse | You will refer to the documentation every time yo use this function and curse the programmer who designed it this way. |
In addition to these mappings the article's mode can override the point system.
| Mode | Rating | Description |
|---|---|---|
| pre-release | Delicate | All the edge cases may not be defined, using it may crash the script or the simulator. |
| rc | Unstable | Subject to radical change and it has the potential to crash the script or the simulator. |
| preview | Unstable | Subject to radical change and it has the potential to crash the script or the simulator. |
Other possible words: Easy, Tricky, Hard, complex, difficult, expert, delicate, intricate, involved, perplexing, quirky, thorny, ticklish, touchy, undependable, unstable, sharp, challenging, demanding, finicky, fussy, hard to please, irritable, obstreperous, perverse, picky, rigid, tiresome, tough, troublesome, trying, unaccommodating, vexing
How to rate an article
To edit the rating field you would use the difficulty template {{Difficulty|points=<points>|title=<title>|<description>|<title>}}.
- The points and and title parameters are optional. points will default to 1.
You do not directly set the rating field, the template lets you make the topic more difficult. Ideally when adjusting a rating you won't just use the template once but for each of the reasons for why it is difficult. This may make it more difficult but makes it easier to catalog and edit.
Some articles will get parts of their rating from the templates they include. Functions that utilize negative indexes are a prime example.
Things to look for
- Does it have a parameter that is particularly tricky?
- Does it have a lot of parameters?
- Does the topic have many caveats?
- Does the topic have bugs?
- Are there many Jiras requesting the same (or a subset of the) functionality but with a more direct or easier to use interface?
Tips
Make your edits count
Idea: If you edit a template, the changes propagate to all the changes that use it. Instead of editing each and every article, edit the templates.
- If it is an 'important issue' that is increasing the rating, put it in the template for that issue (click the "A" link and edit the stub article for the issue).
- If it is a commonly used parameter then put it in the template for that parameter. Example: For inventory items that would be Template:LSL Function/inventory.
Organization
I haven't given the organization of the new section much though. I'm thinking automated sections based on the title and if the title is not included, it goes into the main section.