Pipenv: Documentation is hard for newcomers

[thernstig]

Hi,

I was for quite some time contemplating if I should post this issue or not, but in the end I think it is better to bring forth the issue's I've found as a first-time user. I know how hard it can be to work on a project for quite some time and understand what struggles newcomers have.

The issue I've had is to understand many of the basic commands and ambiguities I've found between them and text in the documentations. Some I've managed to figure out after trial-and-error, but some things I still do not understand.

I am not entirely sure in which format to present this. So I chose an unstructured format just explaining various aspects I had trouble understanding. The troubles come from these two documents:

https://docs.pipenv.org/
https://docs.pipenv.org/advanced/

Here we go:

• Pipenv Features says _"The main commands are install, uninstall, and lock, which generates a Pipfile.lock"_. This made me believe that lock is the only way to generate Pipefile.lock, when in actuality pip install also generates a lock file. I find it generally hard to understand when a lockfile is generated and when it is not. I found no clear explanation of when it is or should be updated. I know, it's a very general comment but it's just an overall feeling.

• On a related note, I understood I could update Pipefile manually and then issue a pipenv lock and it would update the Pipefile.lock. But why? I could as well do pipenv install and it would also update the lockfile.

• My understanding of the best-practice is to have a * to not lock versions in the Pipefile. Pipefile.lock will be the one locking versions. But if a new user clones my git repo and does a "pipenv install" they will not get the Pipefile.lock that looks exactly like my version. Pipfile.lock will be updated with the latest version of the packages specified with "*". I might not have done/updated my own installation in a while and thus they might get faults I do not have myself. Also in a production environment where you build a Dockerfile you might accidently get a version in production you have not tested. I understand the "latest is always best" philosophy, but I am moreso aiming at that it is hard to understand how this works by reading the documentation.

Then I went onto read the Advanced Usage of Pipenv. I battled my way through the documentation.

• Deploying System Dependencies tells us: _"This will fail a build if the Pipfile.lock is out–of–date, instead of generating a new one."_ I have no idea what an out-of-date lockfile is (well, I can guess). Is there a better word for this? Could the "out-of-date" word be described more generically somewhere?

• Deploying System Dependencies also tells us how to deploy our code with the install command. However, one would think that pipenv sync is the correct way to install into a deployment to make absolutely sure you get the correct version. What else is the command for?

• What is even more confusing is that pipenv install has a flag --ignore-pipfile which does the same as pipenv sync. Which one should I use? And when should i use any of them? Because all documentation always tells me to use pipenv install.

[thernstig]

I found more things:

• Example Pipenv Upgrade Workflow says the correct way to upgrade is the command pipenv update --outdated. But with the best-practice to specify no version in the Pipefile (just an asterix) pip install will also update all outdated packages.

• Basic Concepts says _"A virtualenv will automatically be created, when one doesn’t exist."_ and then goes to say _"To initialize a Python 3 virtual environment, run $ pipenv --three"_. This immediately makes one wonder why it says I need to issue pipenv --three as a basic concept, when I actually never really do that? I tried it, and what it does is to re-create my pipenv with the version (three or two) specified if I already have one, which I will have after doing my first pipenv install. All-in-all, it confuses me why both are basic command examples and when to use them.

[uranusjr]

It is, most definitely. We are very short on resources to maintain it, unfortunately. Would you be interested in doing a rewrite? We would be more than happy to explain all the warts and ambiguities, if the effort would be preserved in a useful way.

I would suggest producing an alternative doc format that would be more understandable, and outline what concept should go where. We can then work to make sure all the details are correct, and PR those changes in a little at a time.

[thernstig]

I would have wished my answer would have been a happy _yes!_, but my time is lacking at the moment. I felt I should still contribute with this issue explaining what I found. I am not a technical writer unfortunately, but the main struggle (except for not having enough time) is that I do not understand Pipenv good enough yet to write a good documentation. So it's a mix of everything why I am not interested as of this moment.

[techalchemy]

None of us are technical writers. If you have suggested improvements feel free to make a PR. They don’t need to happen all at once.

[thernstig]

@techalchemy I unfortunately do not have the time, nor the proper knowledge to write the documentation. It should be done by someone who already knows the inner workings of all these issues brought up.

[techalchemy]

@thernstig open source works as a system of contributions; if you have a useful contribution or something of substance to say we are more than happy to take a look -- but we are all volunteers, none of us with formal training in how a giant open source project is supposed to work or be documented, and we all do this in our (very limited) free time -- during which we also triage issues and review, write, merge, and maintain code.

Point being: None of us really know what we are doing, and most of us have very small amounts of time. However, telling us 'this is bad' isn't really actionable; we all understand that there can be better documentation and we would love to make that happen, but I know I don't really understand exactly what is hard to navigate about the documentation. I'm not that good at writing documentation in the first place, and I rarely (if ever) use our documentation, so I'm essentially the worst person to sit here and try to think up ways someone would use it.

We are interested in feedback; more importantly, feedback needs to be actionable to be useful not just to us but to others who are interested in helping out. What was hard to use about the documentation? Were you looking for something specific that you couldn't find? Was it hard to find examples of how to use pipenv? I get that you want us to just say 'yes' and do whatever you imagine would be good, but we are a very small team (usually just 2 of us) and generally this kind of issue is best handled by another contributor. I know you gave some examples of things you didn't like, but _what was it you were trying to do_, and ultimately, when you worked it out, _what would have been helpful instead_? I don't think we need you to speak to the entire world, but for you, personally, what should the documentation have said to be helpful?

[thernstig]

@techalchemy I understand and of course I do appreciate all of that (I try to help where possible too). I had trouble with the ambiguities I listed in the initial post. I genuinely thought I answered many of your questions in my original post, but it is obvious I did not explain it well enough. It's possible this would have been better split into multiple issues. But many of the bullet points are interrelated. Maybe some other happy chap who knows more about pipenv and are good at forumulation words will step up and adress these issues. I posted the issue in the hopes of that it would help.

[manihamidi]

For those who come across this in the future @techalchemy resolves a lot of the confusion surrounding the commands/flags below in his answer on a different thread: https://github.com/pypa/pipenv/issues/2765#issuecomment-415918446

pipenv install 
pipenv lock
pipenv install --skip-lock
pipenv install --ignore-pipfile
pipenv sync
pipenv install --deploy
pipenv install --system
pipenv install --system --deploy

[tapaswenipathak]

Hi folks: Writing a PR.