3 ms·

100% agree. I find it very funny, but in a sarcastic and totally wrong way, when a project's README has an Install section that reads: Run "cargo install myP

by j1elo 5y ago

100% agree. I find it very funny, but in a sarcastic and totally wrong way, when a project's README has an Install section that reads: Run "cargo install myProject" I know Rust, so Cargo is not alien to me. But come on, you know that your install instructions are a bit shitty. Please, choose a target distro, then test your instructions in a clean Docker container. THEN you can sit down knowing you wrote proper guidance for users. EDIT because this comment is being misunderstood: I meant that you should make sure your instructions work as-is from a clean installation of your intended distro(s), regardless of how you prefer to do so; using a Docker container is just my preferred method, but you can also do a clean VM or whatever else, as long as you don't assume anything beyond a default installed system.

qmmmur 5y ago
Hold on, do you not see the insane contradiction of not wanting to rely on having cargo installed but requiring something is deployable and tested in a docker container? What?!
- mouldysammich 5y ago
  If its deployable and tested in a docker container its much easier to generate user images, it takes the onus away from the user and the developer can just put it on the aur/publish a deb
- j1elo 5y ago
  No, you misunderstood. I meant that if you're going to document a block of command-line instructions, you should first make sure those commands work as-is in a clean system. A very easy way to do this (for me anyways) is using a Docker container. I use this method to test all of my documented commands. But there are other ways, of course, like using a clean VM. Regardless, just test the commands without assuming the customized state of your own workstation! The point is that if I follow the hypothetical instructions of running "cargo install something", the result will probably be "cargo: command not found". When you test this in a clean system and find this error message, this places on you the burden of depending on Cargo, so the least you should do is to make sure "cargo" will work for the user who is reading your docs. At a minimum, you should link to somewhere that explains how to install Cargo. tldr: you should make sure your instructions work as-is from a clean installation of your intended distro(s), regardless of how you prefer to do so.
  - qmmmur 5y ago
    You're telling me that people who want to replace a command-line utility are the same people who can't install a toolchain (or just download a binary and put it in their path)?
    - j1elo 5y ago
      As a single-sample statistic I can share with you, I like to think I'm a well seasoned C/C++ developer, and have experience with all sorts of relatively low-level technical stuff and a good grasp on the internals of how things (like e.g. the kernel) work. Yet I got confused the first time ever some README told me to run "npm install blah". WTF is NPM? I didn't care, really, I just wanted to use blah. Conversely, later I worked with Node devs who would not know where to even start if I asked them to install a C++ toolchain. The point is don't assume too much about the background of the people reading your instructions. They don't have in their heads the same stuff you take for granted.
      - qmmmur 5y ago
        There was a time that I didn't know what npm is (I'm not even remotely a web developer). So I used my computer to do some basic research.
        j1elo 5y ago
        Don't focus on the specifics, consider the NPM thing an analogy for any other piece of software. I've found instances where some documentation instructions pointed to run Maven, and the commands worked in their machine because Maven is highly dependent on customizations and local cache. But it failed in other machines that didn't have this parameter configured, or that package version cached locally. And trust me, Maven can be _very_ obtuse and hard to troubleshoot, too much implicit magic happening. Testing in a clean container or VM would have raised those issues before the readme was written and published. Hence my point stands, testing commands in a clean system is akin to testing a web page in a private tab, to prevent any previous local state polluting the test.
deleted 5y ago
[deleted]

by j1elo 5y ago

qmmmur 5y ago

Hold on, do you not see the insane contradiction of not wanting to rely on having cargo installed but requiring something is deployable and tested in a docker container? What?!

mouldysammich 5y ago
If its deployable and tested in a docker container its much easier to generate user images, it takes the onus away from the user and the developer can just put it on the aur/publish a deb
j1elo 5y ago
No, you misunderstood. I meant that if you're going to document a block of command-line instructions, you should first make sure those commands work as-is in a clean system. A very easy way to do this (for me anyways) is using a Docker container. I use this method to test all of my documented commands. But there are other ways, of course, like using a clean VM. Regardless, just test the commands without assuming the customized state of your own workstation! The point is that if I follow the hypothetical instructions of running "cargo install something", the result will probably be "cargo: command not found". When you test this in a clean system and find this error message, this places on you the burden of depending on Cargo, so the least you should do is to make sure "cargo" will work for the user who is reading your docs. At a minimum, you should link to somewhere that explains how to install Cargo. tldr: you should make sure your instructions work as-is from a clean installation of your intended distro(s), regardless of how you prefer to do so.
- qmmmur 5y ago
  You're telling me that people who want to replace a command-line utility are the same people who can't install a toolchain (or just download a binary and put it in their path)?
  - j1elo 5y ago
    As a single-sample statistic I can share with you, I like to think I'm a well seasoned C/C++ developer, and have experience with all sorts of relatively low-level technical stuff and a good grasp on the internals of how things (like e.g. the kernel) work. Yet I got confused the first time ever some README told me to run "npm install blah". WTF is NPM? I didn't care, really, I just wanted to use blah. Conversely, later I worked with Node devs who would not know where to even start if I asked them to install a C++ toolchain. The point is don't assume too much about the background of the people reading your instructions. They don't have in their heads the same stuff you take for granted.
    - qmmmur 5y ago
      There was a time that I didn't know what npm is (I'm not even remotely a web developer). So I used my computer to do some basic research.
      - j1elo 5y ago
        Don't focus on the specifics, consider the NPM thing an analogy for any other piece of software. I've found instances where some documentation instructions pointed to run Maven, and the commands worked in their machine because Maven is highly dependent on customizations and local cache. But it failed in other machines that didn't have this parameter configured, or that package version cached locally. And trust me, Maven can be _very_ obtuse and hard to troubleshoot, too much implicit magic happening. Testing in a clean container or VM would have raised those issues before the readme was written and published. Hence my point stands, testing commands in a clean system is akin to testing a web page in a private tab, to prevent any previous local state polluting the test.

deleted 5y ago

[deleted]