Difference between revisions of "LSL functionality rating"
| Line 28: | Line 28: | ||
|| {{Interval|gte=8|lt=12}} || Expert || You need to read this article more than once and try out the examples. | || {{Interval|gte=8|lt=12}} || Expert || You need to read this article more than once and try out the examples. | ||
|- | |- | ||
|| {{Interval|gte=12|lt=20}} || Guru || You will want to refer to the documentation periodically to refresh your memory. | || {{Interval|gte=12|lt=20}} || Guru || You will want to refer to the documentation periodically to refresh your memory. Which is probably every time you use it. | ||
|- | |- | ||
|| {{Interval|gte=20|lt=∞}} || Perverse || You will refer to the documentation every time yo use this function. | || {{Interval|gte=20|lt=∞}} || Perverse || You will refer to the documentation every time yo use this function and curse the programmer who designed it this way. | ||
|} | |} | ||
Revision as of 13:02, 20 February 2012
This is just a proposal, nothing has been implemented at this time.
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. 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 want to capture and not confuse. Beyond the base functionality and the caveats, an additional modifier is 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.
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.