Install instructions are inscrutable

[mid-kid]

Say, I'm installing pokecrystal on windows 10, I start by reading here: https://github.com/pret/pokecrystal/blob/master/INSTALL.md#windows-10-and-newer

I get linked to the Windows 10 page for WSL, read through it, pinpoint the command: wsl --install. Reboot, sure. The apt-get commands on the page require sudo so after googling around I figure that out and do it.
I figure out where to put the files, that's simple, ok.
Now I get linked to the Linux instructions.

I guess which distribution I'm using, using the window title/icon or just googling. Run the command listed, and then I'm sent to the rgbds page.

here is where the fun really begins.
I'm using WSL, and I was following the Linux instructions, so I check and see this:

I'm not using Arch, so I guess I need the binaries? Where on the release page are they? Where do I put them?

I scroll down to the windows section:

This section just refers back up again, telling me that I should follow the Ubuntu instructions, but they're not there?

This is where most people give up

And every time they do I'm not able to help them without guiding them through each step manually and making up a tutorial as I go. The source building page is about as vague and unhelpful.

Just going through the process casually, I notice various places where one needs to either read really in-depth pages on a tangentially related subject (e.g. the WSL instructions, rgbds install page), have to read between the lines to find missing/assumed context (apt-get is ran under sudo, ubuntu is the distro that's installed by default), or just plain is left to their own devices.

I don't think the RGBDS install instructions work

RGBDS is a tool aimed at people with an interest in writing assembly for old hardware from scratch. These people have the technical background to know what to do when they're told to install "libpng's development headers", and prefer such instructions as it allows them to use them regardless of the specifics of their system. As such, the instructions are written trying to cover all these bases, and explain exactly how everything works. Straightforward instructions for specific systems/distributions do not fit and are not desireable.

This project's audience is filled with people who are just getting into romhacking or just programming in general, and have possibly never touched a unix-like system before. Throwing them straight into a rabbit hole of technical information is not something you want, as it causes them to seek other tutorials at best (e.g. on youtube, which are often more outdated), or get completely turned off from it at worst.

What can be improved

I think this guide could use some inlining. It's great to link to official resources that explain everything in detail, but there should be a quick, low-friction path for at least the most common cases (Win10+WSL), that ideally requires very minimal to no consulting of external resources. It's not terribly complicated to keep it concise while doing so, and linking all the relevant resources for more information.

[mid-kid]

Excuse the winded issue, but this is a result of a buildup of frustration of seeing people struggle with this time and time again, then trying to point them to exactly where they forgot to do something/did something wrong but finding nothing to point to because there's no instructions.

I've talked with the rgbds people before and while there seems to be interest in improving the rgbds install page, I still think it tries to offer too many options, which is a good thing for their purpose, but we want to recommend a specific path instead.

[kanzure]

Just make an installer, or bundle everything together.

[mid-kid]

I'm not opposed to the idea of, for example, packing up an environment with cygwin+rgbds for easy unpack+double-click action on windows.

However, if the idea of an "installer" is having a script that attempts to detect the user's environment, fetches resources from the internet that may change at any point, or etc, I think such a solution is generally to brittle to be worth maintaining.

That all said, I think it's good to have good instructions, even if an installer is to be prefered.

[Rangi42]

The RGBDS instructions are still not truly simplified / optimized for pret users, but they did get recent improvements.

The Windows instructions for WSL now link to the Linux instructions:

And the Linux instructions have a pretty short, self-contained procedure for using the pre-built binaries:

The pokecrystal instructions could explicitly say, for WSL users, to use the pre-built binaries and not worry about a package manager.