Suggestions to improve the doc on sc

Features wanted...
Post Reply
MBaas
Posts: 572
Joined: 15 Feb 2016 21:08

Suggestions to improve the doc on sc

Post by MBaas »

Lately I had an intense battle with the documentation as I tried to get to grips with scripting and I'd need to rant a bit ;) Don't take this as offensive - now that I was successful, I am happier that ever with XY and appreciate the genius(es) behind it even more - so I'd just like to describe my experiences and only a few of the issues I struggled with. And the only intention is to highlight some areas that presented problems to me - and a few suggestions on how that could be avoided. But then again, I'm aware time is limited and I'd rather have Don work on the code of XY than the doc :wink:

To give some background on where I'm coming from: I actually am a software-developer, but I usually work in a completely different world. So it would be useful when entering sc to have a place that gave some understanding of concepts and terminology.

I read the doc starting with the section "Scripting" hoping it would do that. A huge problem I had was finding an explanation of what exactly a "string" is in xys. In hindsight realize this may sound ridiculous - but that's the thing with most of these questions when you start fresh. Those missing fundamentals will keep nagging over and over again.
So, imagine you're newbie and see that page. Given that index, it seems reasonable to expect an entry "Strings" there. Otherwise you wonder about the significance and support for strings eternally.

"Scripting Commands Reference" is an impressive list and starts with a great list. The alphabetic list is great, but I was missing a 2nd list which is especially useful in the beginning: a categorization of commands will help to quickly see what other related commands or functions are available.
As an example, I'd like to present this page. Granted, that needs more space - but hey, we deal with software - it should be possible to generate alternate presentations of the same content ;)

Another example: the doc for "listpane" describes its return as "List of items". That confused me deeply, because in my world a "list" is something different from a "string". And even that term wasn't ever defined, so how could I expect to read about "lists" then? :whistle: Ultimately I understood that a list is just a string. And when manipulating lists, the function "gettoken" can be very useful! (I didn't see that relation hinted anywhere, only reading @highend's source helped me to understand that.)

Aaah, I had to get the off. Feel better. Thanks for reading :wink:
______________________________________________
Happy user ;-)

Post Reply