RFC: LSL Documentation Rating System

[Strife Onizuka]

I work on the LSL documention. I have several documentation projects cooking away but today I would like your opinion on a new rating system for the articles: https://wiki.secondlife.com/wiki/LSL_functionality_rating

The purpose of the project is to make the documentation easier to use for new and old users alike. The method for achiving this is to rate each article and provide a section explaining the rating. By explaining the difficult parts it should make learing how to use the function easy.

Please checkout the proposal here:

https://wiki.secondlife.com/wiki/LSL_functionality_rating

If you have any questions or comments please post them here or on the the proposal discussion page.

https://wiki.secondlife.com/wiki/Talk:LSL_functionality_rating

 

---

Many of you will not be familiar with me personally, I write LSL stub articles, review contributions, and improve the templates that drive the documentation. The best way to get in touch with me is through the wiki.

If you have any ideas on how to make the documentation better please let me know!

[Ela Talaj]

From what I've seen of your code you're a top notch system programmer. Yet a programmer writing documentation is like a shark hunting on land. It is not impossible that once in a while it might jump on the beach and catch something, but not very probable

Documentation is for tech writers.

[Dora Gustafson]

I very much welcome a rating system for the LSL Wiki:smileyhappy:
A few times I contributed to the wiki and I realize it is a monster big task to write it and keep it up to date;
Give a big hand to Strife who obviously is the captain on the wiki ship

The rating suggestions looks good although I am not familiar with how to use templates(I bet it is shocking simple when you can)
I don't see any way to give a review or comment on the articles
Some articles really need to be commented on, especially for being unfriendly to newcomers

Keep up the good work:smileywink:

[Kimm Paulino]

Do you wish to be rating the articles or the functions they describe?  It suggests it is rating articles, but then the ratings appear to relate more to the complexity and difficulty in understanding the function described in the article.

I am not sure what is to be gained from a note on an article that basically tells you that you will always be referring back to the article - I would have thought that this was fairly self evident and people will make up their own mind.  At the end of the day a rarely used function will always have you refering back even if its fairly trivial.

I'm also not sure how a rating telling someone that something is complex or difficult to master will make learning how to use a function easier?

If you are considering a ratings system, what I would rather see personally is some indication of the maturity and accuracy of the information. More of a quality control facility so people can work out how much they can rely on the information in an article.  Possibly ranging from something like "this is brand new, we're still documenting what it goes" all the way up to "this is mature, used by loads of people and has had extensive peer review by the community, and all bugs now seem understood and documented".  That would give everyone an indication of which areas of the document need to improve over others I think ...?  So this would be more of a "confidence in the information" score maybe.

Those were my thoughts on reading your proposal.

Kimm.

 

[Strife Onizuka]

Thank you all for the responses, they are helping.

RE Dora Gustafson I like the idea of a comment section (I wish the templates were shockingly simple but I think to implement this it could be made really simple).

RE Kimm Paulino For an experienced user the rating will be nothing more than a confirmation of what they alread know. The rating system is a bootstarp, it gives you a flavor for the article before you read it, and will link you to an explanation (maybe even an introduction) to the topic.

RE Ela Talaj I won't deny it. Fish out of water, thats me, but I think I'm past the gasping phase. This isn't something that happened over night, more like a fish evolving legs. If you know any technical writers who will work for free, please have them submit a proposal (rewrite llSetTextureAnim lets say). Here are the LSL Portal requirements and things to look out for:

1. We have an ever changing language which is not nicely versioned (nor the changes completely documented).
2. The documentation is only useful if it is relevant, it must incorporate bugs and gotchas as they evolve.
3. It has to be technically complete, it is the official documentation after all.
4. The users want a quick reference and a detailed reference.
5. The users are new and old users. It has to be accessible.

We have requirements that seem to compete with each other! The hardest requirement I have found is accessibility.

[Kimm Paulino]

I'm wondering if I'm missing something here

---

RE

Kimm Paulino

For an experienced user the rating will be nothing more than a confirmation of what they alread know. The rating system is a bootstarp, it gives you a flavor for the article before you read it, and will link you to an explanation (maybe even an introduction) to the topic.

---

So this reads like it will be telling someone unfamiliar with a function that it is a hard one to learn, and read things carefully ...?  But they have no choice really - its not like they will be thinking "oh, if this is a difficult/guru function, then I'll use a different one ..."?

If thats the case, then surely the better thing to be doing is by indicating to the more experienced people where some help is needed to make it more understandable and accessible to a wider audience - maybe ensure gotchas are clearly listed, information hidden away in Jira issues makes it to the wiki, more examples, that kind of thing?

I guess it depends what the aim is here - to help the community build quality documentation or to just warn people about hard-to-use functions ...?  This system sounds like it would do the latter but not help with the former.

When I started out, 3 years ago looking into scripting (as a software engineer of a number of years) the biggest frustration was inconsistent or incomplete documentation (followed closely by quirky functions themselves ).  The wiki's are an amazing feat for a community led effort, but an indication of confidence and maturity in an article would have save learning mistakes that many others have already learnt the hard way.  I don't know that any kind of "here be dragons" indication would have helped at all, but maybe thats just me ...

Kimm.