Project

General

Profile

Actions

Task #20716

closed

Idea #20543: Documentation should stop suggesting `pip install --user`

Review 20543-pip-install-virtualenv

Added by Peter Amstutz about 1 year ago. Updated 12 months ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Actions #1

Updated by Tom Clegg about 1 year ago

  • Assigned To set to Tom Clegg
Actions #2

Updated by Peter Amstutz about 1 year ago

  • Assigned To changed from Tom Clegg to Alex Coleman
Actions #3

Updated by Brett Smith about 1 year ago

  • Start date set to 07/07/2023
  • Status changed from New to In Progress
  • Subject changed from Review to Review 20543-pip-install-virtualenv
Actions #4

Updated by Alex Coleman about 1 year ago

I had a couple comments about things that might potentially increase user readability.

The first comment is when you tell the user they can add the tool to their path. You say how originally they need to run

~/arvclients/bin/arv-get --version

with the full path, or they could add it to their PATH. I thought it could be good to include an example, like saying now
arv-get --version

works.

The second thing is when you explain how another user with read access to your home directory would be able to run those tools, using the users absolute path instead of '$HOME'. Once again, I thought it might be good to include an example like:

export PATH="$PATH:/home/{username}/arvclients/bin" 

Actions #5

Updated by Alex Coleman about 1 year ago

I looked at commit 863c2ec507f778087942fa928bbc414ad75e2afc.

Actions #6

Updated by Alex Coleman about 1 year ago

  • Assigned To changed from Alex Coleman to Brett Smith
Actions #7

Updated by Brett Smith about 1 year ago

Alex Coleman wrote in #note-4:

I thought it could be good to include an example, like saying now arv-get --version works.

Sure, added in b5c22f040.

The second thing is when you explain how another user with read access to your home directory would be able to run those tools, using the users absolute path instead of '$HOME'. Once again, I thought it might be good to include an example like:

I'm less wild about this, because this isn't really an example so much as a template. We have to be very clear to the reader which parts of the text should be changed vs. which shouldn't. This is especially tricky since the line in question uses shell variables (which should be left alone) and template variables (which should get filled in). In my experience, it's difficult to get these followed 100% correctly.

Adding to the complexity is the fact that the template isn't even complete. The /home part isn't reliable either—it'd be /Users on macOS, or possibly other paths on systems that use networked home directories. So the variable isn't as simple as username but more like absolute home directory path.

Honestly, if the version there is too complicated, I'm inclined to just delete this paragraph entirely. There's so many reasons it can fail to work and it's not practical for us to write instructions covering all the cases. I meant it to sort of hint at the possibility for more advanced users, but maybe it's too clever by half. I'm on the fence.

Actions #8

Updated by Brett Smith about 1 year ago

  • Assigned To changed from Brett Smith to Alex Coleman
Actions #9

Updated by Alex Coleman about 1 year ago

  • Assigned To changed from Alex Coleman to Brett Smith

Brett Smith wrote in #note-7:

Sure, added in b5c22f040.

Thanks!

Honestly, if the version there is too complicated, I'm inclined to just delete this paragraph entirely. There's so many reasons it can fail to work and it's not practical for us to write instructions covering all the cases. I meant it to sort of hint at the possibility for more advanced users, but maybe it's too clever by half. I'm on the fence.

I think that's a great point, I'm fine either way.

Actions #10

Updated by Brett Smith about 1 year ago

Alex Coleman wrote in #note-9:

Honestly, if the version there is too complicated, I'm inclined to just delete this paragraph entirely. There's so many reasons it can fail to work and it's not practical for us to write instructions covering all the cases. I meant it to sort of hint at the possibility for more advanced users, but maybe it's too clever by half. I'm on the fence.

I think that's a great point, I'm fine either way.

Removed in 663269d2d0f3ff3fe113cc894d07b0f7f4399b63.

Actions #11

Updated by Brett Smith about 1 year ago

  • Assigned To changed from Brett Smith to Alex Coleman
Actions #12

Updated by Alex Coleman almost 1 year ago

  • Assigned To changed from Alex Coleman to Brett Smith

Brett Smith wrote in #note-10:

Alex Coleman wrote in #note-9:

Honestly, if the version there is too complicated, I'm inclined to just delete this paragraph entirely. There's so many reasons it can fail to work and it's not practical for us to write instructions covering all the cases. I meant it to sort of hint at the possibility for more advanced users, but maybe it's too clever by half. I'm on the fence.

I think that's a great point, I'm fine either way.

Removed in 663269d2d0f3ff3fe113cc894d07b0f7f4399b63.

Great, it looks good to merge to me!

Actions #13

Updated by Brett Smith 12 months ago

  • Remaining (hours) set to 0.0
  • Status changed from In Progress to Resolved
Actions

Also available in: Atom PDF