denizenscript / denizen-for-bukkit-docs Goto Github PK

refer to issue #22

Based on my original complaint on Discord:

mcmonkey05/14/2019
@The_Conductor I'm a bit confused about the ordering of section 1
it seems to be:
TAGS ohbtwhereseverythingelseyouneedtorunascript
COMMANDS which we discussed previously but now here's what they are
THE EX COMMAND which we've already used but you probably are wondering what that is
TASK SCRIPTS which we've been using for 3 sections now but I guess we need to mention that
like
why is everything in the section labeled "Tags"
you could literally have the other 3 sections gone through in full without ever using a single tag
but you can't have tags without the contents of the next 3 sections slipping in
it seems like you'd want tags towards the end of the intro section not the beginning, wouldn't you?

Need to update all section numbers to follow #.#. Section Name format (versus the current #.# Section Name format), since the DIY/example projects section will end up adopting the #. Example Project Name format.

Hi. This is half an issue, half an announcement, I suppose?

I'll start with the announcement. I'm no longer going to be writing any new pages to this project. This is not a continuation of me leaving the Denizen community, nor is it in any way some petty form of "revenge" against anyone. This is merely a result of me having left the Denizen community.

To briefly quote a part of the private message that I had sent to @mcmonkey4eva:

I've given it a lot more thought and I really don't think I should be pushing it forward, particularly since I'm not, you know, actually in the Discord and able to fling ideas back and forth to get a better grasp of what the new features/syntax changes entail

I'm willing to do maintenance and PR checking, but I don't think I'll be able to do much adding to the docs if there's going to be syntactical changes like <def[]> -> <[]> and I'm not really present to discuss it in the depth that would let me know about the feature in the "way it's intended to be used" (for a lack of a better way to phrase that).

So, for a lack of a better alternative to approaching this, I think I'll just be hands-off with the project mostly

Of course, there will be concerns about how I could, in fact, continue adding new pages. Like private messaging mcmonkey each time something new is added, or someone making issues about the new features that were added. Both are, in fact, alternatives, but are not better than having you directly contribute new pages instead.

To address why private messaging mcmonkey over and over again is impractical, well, it's continuous private messaging over any and all features that may or may not be worthy of being added to the text tutorials. To make some things slightly worse, this will also result in mcmonkey becoming something of a secondary megaphone for the community. There's already an issues page for this sort of stuff. I see no need to force mcmonkey to become some sort of courier for every little thing that happens.

To address why new issues about new features being added is equally as impractical, you must understand that the vast majority of my Denizen knowledge stretches well into hundreds upon hundreds of commits behind the current standards, whatever they may be. Me having left the community means that I don't get direct feedback on how certain features can/will be used. At most, my knowledge of a feature will be limited to what is told to me. When such a feature is conveyed to me and I approve of its addition, I will have to play around with it on a personal server, figure out its nuances, then proceed to write an in-depth description of how to use it while not fully knowing how to use it myself, blah blah blah. It becomes a mess of a telephone game where a contributor/dev of the Denizen project adds or changes something, it gets conveyed through most likely a second party, and then is conveyed to me (a third party), who has to interpret what the second party is saying while trying to get down to what the first party intended for the feature to do, so on and so forth. It's much better to cut out that last line of communication and just have you guys directly contribute a page.

Which leads me into saying: Since I am no longer going to be adding new pages, I will instead try to be more accepting of pull requests that do not fully suit up to my standard of writing. Since these circumstances have changed for the weirder side of the unknown, I will have to take to elaborating on the new contribution rules in another time. However, please note that these changes are not guaranteed to make the pull request process any easier. There will still be standards enforced for this project, and failure to abide by the standards will result in closed pull requests.

To move on to the issue part of this, well, issue: I need to add more to the README regarding the limits that I have with this project, and change the contributors' guidelines to accurately reflect the new changes that are to come.

If you have questions about the changes, you may email them to me at [email protected] for as long as this issue is open. To prevent your emails from being regarded as spam, I highly recommend putting "Denizen Text Tutorials" somewhere in your email subject.

When this issue is closed, I will no longer guarantee that I will answer every question sent to the email above, nor will I guarantee that I will leave email addresses unblocked should I come to be annoyed by the sender for any reason that I may come across.

On this line: https://github.com/DenizenScript/Denizen-For-Bukkit-Docs/blame/master/source/docs/basics-of-scripting/memory-flags-and-definitions.rst#L18-L19

I feel like it's unclear that it's just a super minor wording restriction (ie "server" and "global" are the same and we decided to deprecate using alternate words for the same concept)
It reads almost like there was a whole global flag system that's gone now, which concerns me both as just being the wrong implication and the potential for "wow Denizen just removed entire things that are in the tutorial videos" interpretations.

Relatively minor but might be a way to word that better

I had completely forgot that this should be a thing. Thanks to @SXRWahrheit for pointing this out to me on Discord!

These docs here https://docs.denizenscript.com/docs/basics-of-scripting/memory-flags-and-definitions.html
Why are they so wrong they don't even mention the <[defname]> syntax that's been available in D1 for hours already!

A more idea order would be:

1. The /ex command
2. Task scripts
3. Denizen commands and arguments
4. Tags
5. World Scripts
6. The if command
7. Definitions and flags

https://docs.denizenscript.com/docs/basics-of-scripting/an-introduction-to-tags.html
Says:
Put this script in the ./scripts/ folder and load it by using the command /denizen reload scripts.

It should use /ex reload, which is the modern script reload command,

• Add some special information about the DIY/example projects section
• Clarify naming conventions related to sections and subsections
• Be more clear about contributing entire new sections