Documentation is hard for newcomers

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.

[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.