Provide a clearer visual brand identity for the PyPA documentation

[ncoghlan]

Currently, there's no obvious indication when viewing the Python Packaging User Guide itself that it's an officially blessed project of not only the pip/virtualenv/pypi/twine/setuptools development teams, but also of the CPython core developers. The "packaging.python.org" URL isn't enough, especially when the ReadTheDocs link is still better known to search engines.

It would be desirable to align the theming of the Packaging User Guide with that of the main documentation to help make that connection clearer to readers.
The current docs theme components: http://hg.python.org/cpython/file/default/Doc/tools/sphinxext/

(Also see #304 for discussion of the considerations of theme switching in general)

[qwcode]

actually, for a time, the theme was the same as the core docs (that theme is still in the src), but then I decided it was more important to be consistent with the PyPA projects (I had an open issue for that for awhile before I made the change), which were all using the RTD theme, which I happen to think looks better.

I don't personally think the theme is the key to getting more readership, or making it seem authoritative. Here's the most important things I think we should do:

• Announce on python-announce a few times (like every few months for a while) that the "Python Packaging User Guide" is the real deal, and recommended by core docs.
• Get Tarek to take down the old HHGTP (I tried, but no luck so far, Jason does not have access), or even better to be a redirect, or have a BIG note at the top to go to the PPUG.
• If possible, make the references in the core docs even more prominent.
• Be clearer in the PPUG opening paragraph that it's backed by the core docs.

[ncoghlan]

Good idea about promoting on python-announce (and potentially other channels). For that, I think it's potentially best to pitch it as a combined recruitment/announcement post. While the User Guide is the best resource we have, it's definitely still a work in progress. We may also want to note down some guidelines around things like keeping the tutorial aimed at pure Python cross-platform distribution and leaving anything involving compilers or specific platforms to advanced topics, along with some suggestions for possible ways to contribute (like consolidating the setuptools+distutils docs into setuptools, and filling in the blanks in the user guide itself).

As far as this particular issue goes, there is currently zero Python branding on any of the PyPA docs. Why would a reader assume it's authoritative for Python? From a visual perspective, it has no identity at all - just the generic ReadTheDocs theme. It doesn't have to be the full CPython theme, but I think it would be valuable to at least get the official Python logo in there somewhere (and that opinion applies for all the PyPA projects, not just the user guide).

Actually, here's a thought - how about we go dirt simple for a PyPA logo, and just use the intertwined snakes symbol, with "pypa" replacing the usual "python" word mark? If you (along with the rest of pypa-dev) are amenable to that idea, I can follow it up with the board and the trademarks committee.

[qwcode]

As for the python-announce, best I think if you do it. you have more clout frankly to announce it as authoritative : )

yes, I like the logo idea a lot. we've needed a logo for awhile, but got mired in the past on a design.

@dstufft @pfmoore @Ivoz

[dstufft]

I have no opinion on what a logo looks like, other than it'd be nice to have one. We could always hit up twitter to see if one of the designer types feels like doing something. Or whatever I have no cares.

+1 on making us look more official though, especially with packaging.python.org.

[pfmoore]

Nick's logo suggestion sounds sensible (frankly, it avoids the need to design something, so it'll probably save a lot of debate).

I'm also +1 on reusing the Python branding, if that's possible. A bit of PR around the "officially sanctioned" message can't do any harm.

[ncoghlan]

Thanks, I'll follow up on the logo idea with the board. It turns out they're not as well across the consolidation under the PyPA banner that has been going as even python-dev are, so I have some explaining to do that this is about the PSF helping to communicate the emergent direction of the distribution tools development community, rather than trying to impose something from the top down :)

So the order will probably be to get the logo idea sorted first (since that provides a clear indication that the PSF is on board with the idea), and then going the python-announce route to advertise PyPA in general, the Packaging User Guide in particular and to seek additional contributors to start filling in more of the blanks.

[qwcode]

the order will probably be to get the logo idea sorted first

to be clear, are you looking for more consensus from pypa? or from PSF at this point?
I'm all for just doing snakes + "pypa" and being done. to be clear, you mean this, right? https://www.python.org/static/community_logos/python-logo.png

[ncoghlan]

The bit I needed to do was get confirmation that we could use the same font, since Flux Regular is a licensed font rather than a freely available one. The answer to that currently looks to be "Yes", given that packaging.python.org is a PSF subdomain , and there's a pretty clear trail of authorisation due to PEP 453 and the fact I'm also a PSF Director. Explicitly associating PyPA with the PSF as a working group would be ideal, but even though the bylaws have been updated appropriately, the mechanisms to actually do that aren't in place yet.

At this point, I just need to get access to the font files, and then I'll be able to create a PyPA svg based on the existing Python one.

[dstufft]

MY BRAND! http://www.youtube.com/watch?v=V-fRuoMIfpw&feature=kp

[dstufft]

Can we give a PyPA Logo to Fastly once it's done? They asked for one since they host *.pypa.io

[ncoghlan]

Makes sense. I also made a separate suggestion to the board, which is that we should create a "Powering Python" logo (similar to the existing "Python Powered" one), that sponsors and folks providing various parts of the PSF infrastructure can use to advertise their contributions.

[dstufft]

Yea, Fastly asked for one for the PSF too, but Noah directed them towards the logo page on the website.

[qwcode]

made a separate suggestion to the board, which is that we should create a "Powering Python" logo

so what happened with that?

[ncoghlan]

Travel :)

Things are settling back down now, so I'll look into getting this set up.

[gwideman]

I would like to add further encouragement to do more, on each page, to make it clear that this is THE authoritative and officially sanctioned doc site for python packaging topics. Currently, it's at a readthedocs.org URL, which to an average user means that it could be any old random doc. The home page does say it's maintained by PyPA, and provides a link to a glossary entry about PyPA, but this only weakly conveys any level of authority. To be honest, having not visited for 9 months, when I returned here I was unsure whether this was even the PyPA site I remembered, and continued googling to see if I could find it. I encourage some unambiguous statement on each page that this doc is just as official as docs.python.org.

[dstufft]

Technically it's at https://packaging.python.org. Maybe we should move the RTD URL for this (to just a uuid?) and switch it so that the old RTD url just redirects to packaging.python.org?

[gwideman]

Ah-hah... so the problem is that there are multiple paths to this doc, and google is supplying the RTD one (at least to me). Certainly the packaging.python.org URL is far more confidence inspiring.

[gwideman]

I'm not sure if anything's happening on the URL aspect of this, but I've not noticed any difference -- if I'm just finding my way via google or links from other pypa pages, I still always seem to end up at readthedocs.

As a move in a helpful direction, on PYPA pages, how about at least change the top-left [edit -- I said top-right before] "Python Packaging User Guide" link to explicitly point to https://packaging.python.org/index.html instead of to just index.html? This way, even when google takes people to readthedocs, there's some home of discovering the packaging.python.org site.

Next, could there be some clarification or streamlining about where the docs for different PYPA projects are hosted? On page https://packaging.python.org/en/latest/projects.html#pypa-projects, the docs are all over the place, something.pypa.io, pythonhosted.org, readthedocs.org .

The 'pypa' in something.pypa.io URLs suggests that pypa.io is the more official PYPA home than packaging.python.org, yet pypa.io itself doesn't return a DNS entry, and www.pypa.io does, but there's no response from that address.

So, for example, once at the pip doc at pip.pypa.io, there's no link back to any official PYPA site, and no way to reason from the URL about how to get to the "real" PYPA.

I realize that different hosts are used for ease of editing by different authors. But it would be helpful if all PYPA docs agreed on how to show unambiguously that they are part of a coherent PYPA whole, and all had a conspicuous link pointing back to the PYPA home site.

This is all very mundane stuff, but it's underbrush that users, including me, have to hack through just to try to figure out where the authorized trails are.

[ncoghlan]

We were missing the "Canonical URL" setting in the RTFD config, so I've at least fixed that and rebuilt the docs. I'm not sure what impact that really has though...

[ncoghlan]

"all very mundane stuff" is the problem. Open source is essentially a giant, global skunkworks project. We've managed to get vendors to grok that contributing code upstream helps them in the long run, but they still mostly employ their tech writers for product specific docs. So upstream docs = docs written by developers rather than writers = they're not very good by industry standards.

Compound that with the disdain that many open source developers show for non-technical users, and the burden of doc maintenance falls on the shoulders of a very small number of people (devs willing to do it even though they don't find it fun, writers willing to contribute despite the "l-user" crowd).

The bikeshedding over documentation also makes it pretty horrendous to work on upstream without an extremely healthy ego to power "because I said so", since you don't have the "does it even work?" objective metric to fall back on when making design decisions and specific technology recommendations :P

[dstufft]

Generally the pypa.io docs are for the official documentation pages for the various projects. packaging.python.org is a overall "here's a user guide for packaging in general". Other pages are jsut things that haven't switched to pypa yet.

[ncoghlan]

@dstufft @qwcode Perhaps we should cross-link to https://packaging.python.org/en/latest/future.html#major-todos from the projects page?

[gwideman]

@ncoghlan "Canonical URL" -- OK, so the way I read http://read-the-docs.readthedocs.org/en/latest/canonical.html is that this should help google report the best URL for PYPA pages, some time in the future. Good.

To aid convergence on a better future, I still advocate that the Python Packaging Authority banner at top left of each page have a fully spelled-out href to the desired home, either at pypa.io, or at packaging.python.org.

"healthy ego" <-- but I thought you were ordained "czar"? :-)

@dstufft pypa.io <-- OK, if this is to be an official PYPA site, then I urge that:

-- pypa.io and www.pypa.io return pages saying something helpful, if only for way-finding.

-- pypa.io pages each contain a prominent link to whatever is the main home page for PYPA.

[ncoghlan]

@gwideman One of the key tasks of being the designated final authority is to invite the community to get angry at me whenever something breaks, or isn't fixed yet, rather than the folks actually doing the work. It takes a certain amount of underlying arrogance to volunteer for a role like that (and a lot of confidence in your ability to process negative feedback with equanimity). I find it's entirely worth it when I see what self-motivated folks are able to achieve as we start getting at least some of the political road blocks out of their way, though :)

For the other points, agreed, those sound worthwhile to me. One possible approach would be to move the more developer oriented material in the current PyPUG (like the project list and the future plans) out to a separate "PyPA Contributor Guide" and host that at pypa.io (one of the bits of feedback I've got from folks here in Brisbane was that "How can I help?" was a bit hard to find).

[pfmoore]

Regarding pypa.io and www.pypa.io - I don't think PyPA has much of a formal identity, but maybe it's something we should have, and could promote on that front page. Something as simple as:

The PyPA (Python Packaging Authority) exists to .....

Current PyPA projects are:

• pip - http://pip.pypa.io
• setuptools - http://setuptools.pypa.io
• etc

Doesn't have to be anything fancy, just a "this is us, and what we do" sort of statement.

[qwcode]

first, can we just get the logo? : ) that's where all this started

but I agree with @pfmoore that a simple "pypa.io" front page could help.

how about let's make that front page a sphinx project itself? I'll start one.

If we added this container project, then I could see splitting out the developer stuff from the PPUG into that, because then it would be connected into some larger whole, vs just split out into outer space.

[dstufft]

I didn't make a front page mostly because I'm lazy :)

[qwcode]

ok, here: https://github.com/pypa/pypa.io
I'll take a stab at this (and possibly break out the dev stuff from the PPUG; we'll see how that looks)

[ncoghlan]

Using the same font as the Python logo turns out to be a pain, as it has to
be licensed, and thus I can't just edit the text in Inkscape (all the
published SVGs have the text vectorised). Marc-Andre offered to get one of
the designers that worked on the PSF brochure to look into it, but I
haven't heard anything back about that yet.

It may be better to pick a different (freely licensed) font, and just keep
the snake logo and colour scheme.

[ncoghlan]

I have the font files now - will put together an initial attempt at an SVG tonight

[ncoghlan]

PNG attached (since GitHub doesn't allow SVGs on issues). If folks think this is good enough to be useful, suggestions on where to put the SVG are welcome (somewhere in the PyPUG repo, I'm just not sure where).

[qwcode]

I just put it into the pypa github profile, although we probably need a "square" version of it to make that look better? https://github.com/pypa

I'll try putting it somewhere in the PyPUG in a few minutes..

[qwcode]

where to put the SVG are welcome (somewhere in the PyPUG repo, I'm just not sure where).

source/images ?

I'll try putting it somewhere in the PyPUG in a few minutes..

I struggled with where in the theme the logo should appear. I keep thinking a "powered by PyPA" version of the logo that would go in the left bar, although I haven't tried tweaking the theme yet. It may be mobile non-friendly to do that. Maybe it needs to just go in the index page at the bottom so as to not mess up compatibility? not sure.

[ncoghlan]

With #305 merged, I think my original concern here has been addressed.