Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Transform install_deps.sh into a markdown guide #1059

Open
ethteck opened this issue May 20, 2023 · 0 comments
Open

Transform install_deps.sh into a markdown guide #1059

ethteck opened this issue May 20, 2023 · 0 comments
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers

Comments

@ethteck
Copy link
Member

ethteck commented May 20, 2023

To quote me in #1051 :

I'll try to explain my reasoning for why a human-readable doc is better than a bash script in this case.

For starters, we end up installing things without really informing the user, running sudo. I think this is pretty bad practice, and I know it's been raised before as something to consider. I also think it's just generally better to have users install their own dependencies instead of running a bunch of commands for them. We of course can provide said commands, but running the commands automatically in their native environment to install system packages has always felt a bit intrusive to me.

Also, as we see in cases like these, if the feedback we expect doesn't exactly match what the bash script checks, the script just totally gives up or fails. Whereas a human-readable doc might lead someone to the correct solution.

In both cases, insufficiencies in the script/doc would lead people to ask for help and then we'd fix said script or doc. What's nice about the doc, though, is that it allows us to easier add notes and caveats that someone might care about instead of littering the shell script with logic and/or print-outs that will be drowned out by the other output from commands.

I guess you could ask "why not both?" and to that I'd say that maintaining two things is even worse than one. So I'd really prefer not to do that, but I acknowledge it'd be the best of both worlds...just at the expense of 2x the maintenance work.

After #1055 is merged, install.sh will only contain external (system) dependencies, at which point it can be replaced with a guide that can help people obtain the required dependencies for the project.

@bates64 bates64 added documentation Improvements or additions to documentation good first issue Good for newcomers labels May 24, 2023
@bates64 bates64 changed the title Transform install.sh into a markdown guide Transform install_deps.sh into a markdown guide Feb 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers
Projects
None yet
Development

No branches or pull requests

2 participants