LSL functionality rating - Revision history

Strife Onizuka at 23:44, 20 February 2012

2012-02-20T23:44:29Z

← Older revision		Revision as of 16:44, 20 February 2012
Line 6:		Line 6:
	== Project ==		== 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.		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 "{{HoverText\|important issues\|An important issue is generally a bug but it may just be an unexpected 'expected behavior'. We can't assume they are bugs.}}" that modify how difficult it is to master the functionality, some are obscure edge cases, others are huge functionality changes or deficiencies.		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 "{{HoverText\|important issues\|An important issue is generally a bug but it may just be an unexpected 'expected behavior'. We can't assume they are bugs.}}" that modify how difficult it is to master the functionality, some are obscure edge cases, others are huge functionality changes or deficiencies.
Line 108:		Line 108:
	* 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 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]].		* 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.

Strife Onizuka: /* Rating Map */

2012-02-20T21:55:40Z

Rating Map

← Older revision		Revision as of 14:55, 20 February 2012
Line 18:		Line 18:

	{\| {{Prettytable}}		{\| {{Prettytable}}
			\|+ ''I pulled these numbers out of thin air along with the graduations. Thoughts?''
	\|- {{Hl2}}		\|- {{Hl2}}
	! Points		! Points

Strife Onizuka: /* Project */

2012-02-20T21:48:58Z

Project

← Older revision		Revision as of 14:48, 20 February 2012
Line 8:		Line 8:
	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.		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 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 "{{HoverText\|important issues\|An important issue is generally a bug but it may just be an unexpected 'expected behavior'. We can't assume they are bugs.}}" that modify how difficult it is to master the functionality, some are obscure edge cases, others are huge functionality changes.		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 "{{HoverText\|important issues\|An important issue is generally a bug but it may just be an unexpected 'expected behavior'. We can't assume they are bugs.}}" that modify how difficult it is to master the functionality, some are obscure edge cases, others are huge functionality changes or deficiencies.

	===Proposal===		===Proposal===

Strife Onizuka: /* Project */

2012-02-20T21:48:25Z

Project

← Older revision		Revision as of 14:48, 20 February 2012
Line 8:		Line 8:
	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.		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 "{{HoverText\|important issues\|An important issue is generally a bug but it may just be an unexpected 'expected behavior'. We can't assume they are bugs.}}" that modify how difficult it is to master the functionality, some are obscure edge cases, others are huge functionality changes.		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 "{{HoverText\|important issues\|An important issue is generally a bug but it may just be an unexpected 'expected behavior'. We can't assume they are bugs.}}" that modify how difficult it is to master the functionality, some are obscure edge cases, others are huge functionality changes.

	===Proposal===		===Proposal===

Strife Onizuka at 21:38, 20 February 2012

2012-02-20T21:38:39Z

← Older revision		Revision as of 14:38, 20 February 2012
Line 1:		Line 1:
	{{Warning\|This is just a proposal, nothing has been implemented at this time.}}		{{Warning\|This is just a proposal, nothing has been implemented at this time.<br>
			Please comment on the [[{{TALKPAGENAME}}\|discussion page]] or in the forum thread:
			http://community.secondlife.com/t5/LSL-Scripting/RFC-LSL-Documentation-Rating-System/td-p/1392455
			}}

	== Project ==		== Project ==

Strife Onizuka: /* How to rate an article */

2012-02-20T21:13:01Z

How to rate an article

← Older revision		Revision as of 14:13, 20 February 2012
Line 87:		Line 87:

	Some articles will get parts of their rating from the templates they include. Functions that utilize negative indexes are a prime example.		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]].

Strife Onizuka: /* Rating Map */

2012-02-20T21:02:45Z

Rating Map

← Older revision		Revision as of 14:02, 20 February 2012
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.
	\|}		\|}

Strife Onizuka at 20:58, 20 February 2012

2012-02-20T20:58:50Z

← Older revision		Revision as of 13:58, 20 February 2012
Line 1:		Line 1:
	{{Warning\|This is just a proposal, nothing has been ~~decided or~~ implemented at this time.}}		{{Warning\|This is just a proposal, nothing has been implemented at this time.}}

	== Project ==		== Project ==

Strife Onizuka at 20:58, 20 February 2012

2012-02-20T20:58:04Z

← Older revision		Revision as of 13:58, 20 February 2012
Line 1:		Line 1:
			{{Warning\|This is just a proposal, nothing has been decided or implemented at this time.}}

	== Project ==		== Project ==

Strife Onizuka: /* Rating Map */

2012-02-20T20:56:22Z

Rating Map

← Older revision		Revision as of 13:56, 20 February 2012
Line 16:		Line 16:
	! Points		! Points
	! Rating		! Rating
			! Description
	\|-		\|-
	\|\| {{Interval\|gte=0\|lt=2}} \|\| Easy		\|\| {{Interval\|gte=0\|lt=2}} \|\| Easy \|\| Like falling off a log, why does this article even exist?
	\|-		\|-
	\|\| {{Interval\|gte=2\|lt=5}} \|\| Tricky		\|\| {{Interval\|gte=2\|lt=5}} \|\| Tricky \|\| Mostly obvious but the examples make everything plain.
	\|-		\|-
	\|\| {{Interval\|gte=5\|lt=8}} \|\| Hard		\|\| {{Interval\|gte=5\|lt=8}} \|\| Hard \|\| You need to actually read the article. You will regret not reading the caveats section.
	\|-		\|-
	\|\| {{Interval\|gte=8\|lt=12}} \|\| Expert		\|\| {{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		\|\| {{Interval\|gte=12\|lt=20}} \|\| Guru \|\| You will want to refer to the documentation periodically to refresh your memory.
	\|-		\|-
	\|\| {{Interval\|gte=20\|lt=∞}} \|\| Perverse		\|\| {{Interval\|gte=20\|lt=∞}} \|\| Perverse \|\| You will refer to the documentation every time yo use this function.
	\|}		\|}

			In addition to these mappings the article's {{HoverText\|mode\|Article mode is used primarily to display an error message at the top of articles and limit how an article is categorized.}} can override the point system.

			{\| {{Prettytable}}
			\|- {{Hl2}}
			! 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,		Other possible words: Easy, Tricky, Hard, complex,
	difficult,		difficult,