search

nektos / act

Run your GitHub Actions locally 🚀
https://nektosact.com
MIT License
54.5k stars 1.36k forks source link

Manual installation guide can be difficult to understand #2455

Open julisod opened 1 month ago

julisod commented 1 month ago

Details

I had a lot of issues figuring out how to install Act, and I feel like I some people might have similar struggles. I didn't have any of the package managers installed, so I tried the bash script. It says that it's executable on any systems, but it didn't work for me on windows, so I assumed it works on unix systems. So I went for the manual installation.

First issue was that I didn't know which file to download since I didn't know what the difference between them was. Took me a while to figure out it was about the CPU architecture and then to also figure out which one I have.

Second issue was that I didn't know what adding something to the PATH variable meant and how to do that.

Maybe this is me not being skilled enough with computers, but it would be nice if the installation guide was made as easy to understand as possible. The instructions could be more detailed, or maybe include links to external sites that walk you through the individual steps.

sebastien-perpignane commented 3 weeks ago

First issue was that I didn't know which file to download since I didn't know what the difference between them was. Took me a while to figure out it was about the CPU architecture and then to also figure out which one I have. Second issue was that I didn't know what adding something to the PATH variable meant and how to do that.

I read a lot of installation guides (I'm an old man) and, to be totally honest, act guide is perfectly clear.

Manually installing a software requires some skills. Understanding that you have different binaries for different CPU architectures and adding a command to the PATH are one of them.

Now I think you can perceive your experience with this installation guide from two points of view:

  1. the installation guide needs to be more detailed
  2. by trying to manually install act, you acquired new skills that are needed to install softwares manually

I think the 2nd option is the best one :)

TheFabulousDeath commented 3 weeks ago 
I read a lot of installation guides (I'm an old man)

Not trying to gotcha you, but don't you think that's exactly why you would think that it is perfectly clear?

2. by trying to manually install act, you acquired new skills that are needed to install softwares manually

I guess we agree that if the installation guide was more detailed, it would make the experience better. Why shouldn't this be the resource from which someone learns to install programs manually?

I can't see why this wouldn't just combine the positives of 1 and 2.

julisod commented 3 weeks ago

I know that it would've been easy if I was more experienced with installing programs manually, the point was more that I'm not 😢 I was thinking about how easy this would be to use for a newbie (me). Glad that I learned something new, but I was also close to just giving up because of the complexity.

This is just in case someone else ends up having the same problem, because if I'm the only one who would have this issue, it's not really an issue.

sebastien-perpignane commented 3 weeks ago

@TheFabulousDeath

don't you think that's exactly why you would think that it is perfectly clear?

Hehe honestly, no :) I think it is perfectly clear because I read lot of installation guides not containing that level of details and not proposing 9 package managers to facilitate the process of installation instead of installing manually.

For example, the guide says:

You can unpack and run them in terminal specifying full path or add them to one of the paths included in PATH environment variable.

All you need to do is search "what is path environment variable" on your favorite search engine.

First result when using duck duck go is :

PATH is an environment variable on Unix-like operating systems, DOS, OS/2, and Microsoft Windows, specifying a set of directories where executable programs are located. In general, each executing process or user session has its own PATH setting

And what if a reader of the guide does not know what is an environment variable ? Do you think it should be explained in the act installation guide too ? Do you see what I mean ?

@julisod

I totally understand. I don't forget the time when I was a newbie and when these kinds of guide were difficult for me too. But a guide to install a specific program cannot also be a linux guide or a CPU architecture guide. It must consider that some prerequisites are already acquired. At least, that's what I think. Maybe the maintainers of act won't agree with me, after all :)