Skript: State of example scripts

[bensku]

Current example scripts are outdated. They're also often not terribly good examples, which is probably quite confusing for newbies. And, finally, they not all of them work. This needs to change.

I have three potential fixes which I would like feedback on.

Just remove them

Remove example scripts from Skript. Point users to online resources for usable scripts and tutorials.

Fix current examples

Fix current example scripts that do not work. Check all of them for style issues and do changes as needed. Possibly introduce a few new examples for new Skript features.

Rework example scripts

Throw most, if not all, of current examples to rubbish bin. Create new ones, and this time, actually design them to teach new users. Add both very simple (/hat) and somewhat more complex (a simple chat system) examples.

Don't dump example scripts in scripts directory on first load, but instead allow doing that with commands. Possibly allow running unmodified example scripts from Skript jar directly.

I'm honestly not sure which option is the best. First one would require the least amount of effort, while the third option would definitely require a lot of outside contributions.

[APickledWalrus]

I’d say that reworking and fixing them is probably the best idea. I remember looking at the scripts when I first started, so they can come in handy for beginners.

[Blueyescat]

What about a GitHub repository for official example scripts (not for dumping into the scripts folder)? It would be easier to manage the scripts and its README would contain a "how to load" info, this would also teach the users how to load a ready to use script. But all PRs should be reviewed properly in that repository, it should not be a place to share big scripts, scripts shouldn't contain author/contributors info.

Thus a new Skript release wouldn't need to update the scripts, the scripts folder wouldn't be ugly on first load. But there should be a file that leads the user to the examples repository.

I don't really think it is worth to work on a command system right now.

---

Edit: I may change my mind lol, it might be better to just keep them in the scripts folder, just update them.

[jaylawl]

I remember when i first downloaded Skript, that i was very grateful for the provided example scripts and they instantly taught me how stuff works on a basic level. I think they should stay in

[bensku]

@Blueyescat Separate git repository would be good in any case. It can be included in jar if needed by using git submodules.

[Matocolotoe]

I think they should work the same as the new aliases, on a seperate repository and able not to load by default.

[gmalone]

Who are the key players in the world of Skript that are available, willing and can get a cleanup reorganization underway resulting in an authoritative Sk-code reference repository?

[gmalone]

As a relatively new user of Skript -- but a highly experienced coder in many langs over decades -- I must make this comment about Skript and its documentation. Skript may be mostly fine as it is, but the docs are far too sparse, thus limiting the long term potential of Skript, and in the 'plugins' world leading to sometimes deserved mockery, though often just ignorant mockery. It doesn't have to be that way.

All categories of Skript documentation desperately need more working examples, as this submitted issue asserts. Case in point -- how to build and implement custom commands and their arguments. The several existing documentation sites are poorly supported with solid examples -- limiting information to bare syntax and rare examples.

The core problem immediately arising with Skript is the confusing variety of ways things can be expressed. Though the intent must've been to make Skript a "natural language" device, it only makes things more complicated and unclear about what any given correct syntax might be. Thus, the lack of a central repository of syntax AND usage examples is a major hurdle for new users.

Here in late 2019 Minecraft is beginning to experience a resurgence after a drought that began after the sale to Microsoft and lost focus for the game's future. But Microsoft/Mojang are starting to get their Minecraft game on, and the world is reacting, including developers. My recommendation is that whoever has the capacity to drive a new wave of cleanup and clarification of Skript should do so soon and with purpose.

[bensku]

I agree with @gmalone; both Skript and the documentation really need improvements. Unfortunately, I don't think we can address all major issues anytime soon. To put it simply, I (and, as far as I know, other Skript developers) don't have enough time.

Skript, unfortunately, has a huge learning cliff for people who want to dive into its Java code. This is mostly due to missing documentation, and in my opinion, is slowly improving.