Revisit "Package" vs "Distribution" vs "Distribution Packages"

[ncoghlan]

To align with my changes to the stdlib docs, I tweaked a couple of section titles to use the term "Distribution Packages" rather than "Distributions": 4c2e875

However, that introduced something of an internal inconsistency within PyPUG, so I created this issue to specifically consider how to handle this long term (the bare "Distributions" really didn't work in the context of the standard library docs, and I'd like to keep the two as consistent as we feasibly can).

[cjerdonek]

By the way, is the word "dist" free for this? It's already sort of familiar to people because we have sdist and bdist.

Also, you should probably include this variant in the glossary ("Distribution Package" I mean).

[ncoghlan]

See issue #89 for a lot more on the terminology challenges :P

The problem with "dist" is mostly its awkwardness as a word. "dists" is really quite hard to say. I think it may be the best option we have available, given the existing sdist and bdist naming.

[ncoghlan]

The CPython docs update where I ran into the problem: https://hg.python.org/cpython/rev/3acb94e1bab8

[qwcode]

as much as it pains me to go back and forth on stuff, I'm wondering if the original double meaning of "Package" was actually not so bad, given the alternatives. "Distribution Package" seems so cumbersome to me for the PyPUG. As it is now, you've only tweaked a few titles, but we're still left with a lot of bare uses of "Distribution", so it does feel confusing. I can't imagine saying "Distribution Package" over and over again in the PyPUG, and if "Distribution" alone doesn't work in the core docs, then to me, that leaves "Package", but always linking to the glossary term, so users can get the story and how the term is overloaded, and why we're not using "Distribution" alone. We could even write an Advanced section on the whole analyses of the problem of terminology for this.

[pfmoore]

@qwcode I pretty much agree. The word "distribution" feels unnatural every time I use it and I end up mangling sentences to try to work around it. It's unfortunate that "package" means multiple things, but (given Linux distro and Python Distribution) so does "distribution". I think that no matter how much we try to promote a new term, people will keep using "package" in everyday discussion. Maybe it's time to accept that and move on. Practicality beats purity and all...

[cjerdonek]

I think I see a possibility for agreement. How about if we stop using the word "Distribution" as a stand-alone term for the reasons Nick mentioned, and we use the word "Package" for the reasons @qwcode and @pfmoore mentioned. But we prefix Package as "Distribution Package" whenever it's necessary to avoid ambiguity or be precise (presumably these cases will be rare).

I don't know if the docs ever took that approach in a previous iteration.

A funny thing is that I also think "Distribution" is very cumbersome, and I can't imagine ever saying that I would "install a distribution." But I have no problem whatsoever talking about uploading "source distributions," etc. The combined phrase rolls off the tongue much more easily. As a final note, because of built distributions and source distributions, I don't think we'll ever be able to get away from the term "distribution" entirely either.

[ncoghlan]

Distribution package in section titles to avoid ambiguity, and just
"package" as the typical term in the body of the text would sound good to
me. That aligns pretty well with my original suggestions for the
terminology guide as well.

We can also be happy that we tried the "distributions" experiment and it
didn't work out. I "tried it, really didn't like it" is a better place to
be than just assuming we were stuck with the ambiguous dual meaning of
"package".

[ncoghlan]

Issue #87 was the original issue regarding the ambiguity of "package".

[cjerdonek]

If no one else has started, I could put together a PR for this.

[ncoghlan]

The "distribution package" vs "import package" was a relatively novel phrasing that came up in the discussions on #87 (and was subsequently pulled out to #89).

I think it's definitely worth trying an approach that goes with something like:

• "distribution package" in headings
• "package" in body text, unless it's genuinely ambiguous, then "distribution package" or "import package" as appropriate
• we keep the "Python Packaging Index" change (since that aligns nicely with the expansions of PyPA and PyPUG)

If you have time to put together a PR, it would be good to see how it looked in practice.

[cjerdonek]

That sounds fine. The only thing I'm wondering about is the heading suggestion. Are you saying, for example, that the heading for the installing tutorial should read, "Tutorial on Installing Distribution Packages"? I'd be concerned that would confuse newcomers that are just trying to learn how to "install a package" (especially since "Distribution Package" is an invented phrase). What about using the common wording in the heading, but the full phrase in the first sentence of the text (with a link to the glossary)?

[ncoghlan]

I'm happy for the "only when ambiguous" case to apply to headings as well. I suspect the two I already changed would actually be OK with just "Packages" - it was "Distributions" that was ambiguous on the standard library side.

[qwcode]

yea, I think I'd like the headings to be just "Package" as well.
@cjerdonek , I haven't started a PR. go for it.