Lessons from HayesGaze's video

[its-miroma]

Just a bunch of ideas I jotted down after watching Hayes' video:
https://www.youtube.com/watch?v=RZb-3PIhz74

• Should we standardise the Prerequisites sections? Maybe as checklists?
• Sections of the Docs, especially the Creating Your Firsts pages, should dedicate more space to explaining why we're doing things. Create this, add this, use this helper, does not allow the user to understand the reason for these classes.
• We still don't have a page/definition of registries (:
• We should mention that we do not include imports in the code blocks - both in cgl and in the introduction - because they are detected by the IDE or they can be found in the reference mod files.
• We should advise modders to be careful with old posts / code / tutorials, because of the many changes to Minecraft over the last few years (deobfuscation, rendering, data-driving, etc)
• Maybe we could recommend some trusted video tutorials? Obv we would label them as third-party, and we would ask for permission, but for example Kaupenjoe's playlist comes to mind.
• "WHY ARE THEY CHANGING IT AGAIN" 😭✌️
• I was thinking of repurposing https://fabric-docs.netlify.app/ (currently fully broken lol) as a stable URL for the previews of upcoming versions. In other words, when we run the bump script to bump to 26.3, that URL should link to the 26.3 WIP pages (with a clear banner). That way, we can have the WIP versions linked to in prod. Hayes recorded their video on the 21st of June, when Cassian's port/26.2 already existed, but they never found out. And they wouldn't have been able to until a month later.
• Maybe, as a suggestion for new modders, we could ask them to avoid the latest version if we haven't even merged it yet to the docs. Especially with how quickly Mojang is changing things, we could add a disclaimer to "use a more established version" if you are new to modding. I'm not saying 1.21.11, I'm just saying: don't use 26.2 5 days after release.
• We need a better way of explaining the folder structure. I need to study whether there exists already some kind of md-it plugin, or vitepress plugin, for that, or if I should code (or vibecode) something for that. "Starlight" apparently offers something similar that I like: https://starlight.astro.build/components/file-tree/
• Guidite is a pun on a material for the guide, but maybe we can change that for clarity (related: Give ExampleMod a Consistent Theme #562)
• We need to find a way to let modders understand that they can change the IDs of things when they add them. Just look at this: https://github.com/search?q=guidite_&type=code
• Seems like the page on Events does not explain their sidedness (related: Developer Guides: Sidedness #230)
• Should we add those annoying tips / hints for people about the features that the Docs have? for example, if we detect someone scrolling a code block a lot, we can suggest using FullscreenCode, or we can highlight the Resources section to get people to know about it. This would be controlled by localStorage, and there would be an option to disable all tips.
• "Unless what you're doing is really quite simple and has been done a lot of times, there's like barely any information on the internet." This is absolutely true. I had this grand idea about a possible solution: I was thinking that the Docs could host a showcase section, with three monthly challenges for experienced modders, to create a minimal working version of some simple thing. For example: "Add an item that changes the user language at random", or "Make it so that the desktop background changes depending on which dimension the player is in" - relatively simple things for experienced modders, which cannot take more than a few hours, but they are so niche that newcomers cannot realistically figure them out without a lot of headaches. My biggest issue with this, however, is updating the code snippets to new versions. idk I need to think about this more.

[cputnam-a11y]

With the showcase challenges, I do like the idea, perhaps the solution would be not to port them, but instead to simply issue new challenges when an area becomes under represented. Presumably all submissions will be under cc0, so if a new challenge is similar enough to an old challenge, participants should be able to repurpose any code useful to the new example