Hacker News Reader

Comment by j1elo | Hacker News Reader

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.

View on HN

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?!

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.

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)?

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.

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.

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.

Testing in a clean container tests deploying in a clean container. For me, I run a computer :) Maven sounds like a nightmare tbh so I can understand that that specific piece of software has warts. That said, a good piece of package management software will be relatively agnostic to where its run and have a dependable set of behaviours. I much prefer that to a world where every bit of software is run on any conceivable combination of OS and hardware. What an absolute drain on brain space and creative effort!

As someone who authors another shells (coincidentally similar to nushell) I can tell you that you'd be surprised at some of the bug reports you get.

Frankly I prefer the 10,000 approach suggested by XKCD: https://xkcd.com/1053/

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

Reply on news.ycombinator.com