Update landing page #326

theacodes · 2017-06-15T23:47:15Z

Use friendlier language
Be more authoritative
Briefly explain the various types of documentation here.

theacodes · 2017-06-15T23:47:31Z

Towards #317

ncoghlan

LGTM, so once the build issue is resolved, I say go ahead and merge it :)

ncoghlan · 2017-06-16T07:03:14Z

Taking a closer look at the build issue, it's just the reminder to update the reference set of deep links.

ddbeck · 2017-06-16T08:23:34Z

source/index.rst

-The "Python Packaging User Guide" (PyPUG) aims to be the authoritative resource
-on how to package, publish, and install Python projects using current tools.
+Welcome to the *Python Packaging User Guide*. This guide provides documentation
+on how to distribute and install Python packages.


The revised text here seems to be a lot less clear about what distinguishes this guide from, say, the setuptools or pip docs. If this text is going to change, I'd like to see it be even more reader focused. How about something like Welcome to the *Python Packaging User Guide*, a collection of tutorials and references to help you distribute and install Python packages. Or something like that. We can workshop it a bit. 😃

I like it, updated. :)

ddbeck · 2017-06-16T08:29:59Z

source/index.rst

+
+Additionally, there is a list of :doc:`other projects <key_projects>` maintained by members of the Python Packaging Authority.
+
+Index


Index should be Contents

ddbeck · 2017-06-16T08:30:31Z

source/index.rst


-.. _docs.python.org: http://docs.python.org
+Get started
+===========


This (and the following headings) ought to be level 2.

ddbeck · 2017-06-16T08:30:35Z

source/index.rst

-To follow the development of Python packaging, see the `Python
-Packaging Authority <https://www.pypa.io>`_.
+This guide is maintained on `GitHub`_ by the `Python Packaging Authority`_. We
+happily accept any :doc:`contributions and feedback <contribute>`. :)


Gratuitous personal preference: change :) to 😄

ddbeck · 2017-06-16T08:38:59Z

source/index.rst

+
+If you want to learn how to package and distribute your projects, see the :doc:`tutorial on packaging and distributing <tutorials/distributing-packages>`
+
+More resources


If the ToC below is going to show more depth, then I don't think this section is necessary. Skip right to the ToC.

I actually want to try to hide the ToC on this page, gotta tweak the theme a bit to get that to work.

Okay, toc hidden, you can check it out here: http://temp.theadora.io/pypug-326/index.html

OK. I'm not in love with not having the full ToC visible anywhere, but I'll cope. A couple more comments coming up, in this case.

Maybe retitle this section as "Learn more" for parallelism with "Get started"

ddbeck · 2017-06-16T16:34:02Z

source/index.rst

+
+If you want to learn how to package and distribute your projects, see the :doc:`tutorial on packaging and distributing <tutorials/distributing-packages>`
+
+More resources


OK. I'm not in love with not having the full ToC visible anywhere, but I'll cope. A couple more comments coming up, in this case.

ddbeck · 2017-06-16T16:35:09Z

source/index.rst

+
+If you want to learn how to package and distribute your projects, see the :doc:`tutorial on packaging and distributing <tutorials/distributing-packages>`
+
+More resources


Maybe retitle this section as "Learn more" for parallelism with "Get started"

ddbeck · 2017-06-16T16:45:33Z

source/index.rst

+* :doc:`guides/index` that walk you through a specific task.
+* :doc:`discussions/index` that provide comprehensive documentation on specific topics.
+* :doc:`specifications/index` for detailed information about packaging specifications.
+


If these bullets are going to signpost the rest of the ToC, let's be a little be a little more forthcoming about what these sections contain. How about something like this:

* :doc:`guides/index` for walk throughs, such as :doc:`guides/installing-using-linux-tools` or :doc:`guides/packaging-binary-extensions` * :doc:`discussions/index` for in-depth references on topics such as :doc:`discussions/deploying-python-applications` or :doc:`discussions/pip-vs-easy-install` * :doc:`specifications/index` for packaging interoperability specifications

Good suggestion, done.

One minor thing: can we lose the periods on the ends of the bullets? It's a list of things, not really completely sentences

ddbeck · 2017-06-16T16:48:02Z

source/index.rst

+* :doc:`discussions/index` that provide comprehensive documentation on specific topics.
+* :doc:`specifications/index` for detailed information about packaging specifications.
+
+Additionally, there is a list of :doc:`other projects <key_projects>` maintained by members of the Python Packaging Authority.


members of the Python Packaging Authority -> the Python Packaging Authority

Well, probably? I'm not sure the distinction between members and the PyPA itself is meaningful. I assume it isn't and figure this change would be consistent with the other line about the PyPA above.

I think it's important here to keep the distinction, some of these projects are rather independent.

OK, sounds good.

theacodes · 2017-06-16T18:28:35Z

Thanks for the review, @ddbeck!

ncoghlan · 2017-06-17T03:26:25Z

I like the update, but it turns out that the paragraph based structure of the Get started section made the tutorial links less obvious to me than the bullet points in the Learn More section.

What do you think about laying out that section something like:

Get Started

Essential tools and concepts for working with the Python Packaging ecosystem are covered in our Tutorials section:

to learn how to install packages, see the tutorial on installing packages.
to learn how to package and distribute your projects, see the tutorial on packaging and distributing

That way, all 5 of the key links on the page (installation tutorial, publishing tutorial, guides section, discussion section, specification section), would all be highlighted as bullet points.

ncoghlan · 2017-06-17T03:27:31Z

(PR incoming, as I originally didn't write one because I wasn't sure how I thought the section should look, but articulating the question clarified what I actually wanted)

theacodes · 2017-06-17T03:28:57Z

Sounds good. Looking forward to the PR. :)

…

On Fri, Jun 16, 2017 at 8:27 PM Nick Coghlan ***@***.***> wrote: (PR incoming, as I originally didn't write one because I wasn't sure how I thought the section *should* look, but articulating the question clarified what I actually wanted) — You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHub <#326 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAPUc4wIA3WYnG2XAUW9XtDkfqxhfEkAks5sE0ejgaJpZM4N73m5> .

ncoghlan · 2017-06-17T03:36:14Z

@jonparrott already reviewed it, but for future reference: #327 :)

Use friendlier language Be more authoritative Briefly explain the various types of documentation here.

Update landing page

49ba6a4

theacodes requested review from ddbeck and ncoghlan June 15, 2017 23:47

ncoghlan approved these changes Jun 16, 2017

View reviewed changes

ddbeck reviewed Jun 16, 2017

View reviewed changes

Jon Wayne Parrott added 2 commits June 16, 2017 08:56

Address a few review comments

6fc600c

Hide the toc in the body of the index page

aee2dfd

ddbeck reviewed Jun 16, 2017

View reviewed changes

Jon Wayne Parrott added 2 commits June 16, 2017 10:38

Address review comments

766087d

Links for the link god

5485e1c

theacodes force-pushed the new-landing-page branch from 088a6bf to 5485e1c Compare June 16, 2017 17:38

ddbeck approved these changes Jun 16, 2017

View reviewed changes

Address final comments

88441c6

More links for the link god

260f576

theacodes merged commit 78c0d91 into pypa:master Jun 16, 2017

theacodes deleted the new-landing-page branch June 16, 2017 19:09

ncoghlan pushed a commit to ncoghlan/packaging.python.org that referenced this pull request Jun 24, 2017

Update landing page (pypa#326)

c0bff04

Use friendlier language Be more authoritative Briefly explain the various types of documentation here.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update landing page #326

Update landing page #326

theacodes commented Jun 15, 2017

theacodes commented Jun 15, 2017

ncoghlan left a comment

ncoghlan commented Jun 16, 2017

ddbeck Jun 16, 2017

theacodes Jun 16, 2017

ddbeck Jun 16, 2017

theacodes Jun 16, 2017

ddbeck Jun 16, 2017

theacodes Jun 16, 2017

ddbeck Jun 16, 2017

theacodes Jun 16, 2017

ddbeck Jun 16, 2017

theacodes Jun 16, 2017

theacodes Jun 16, 2017

ddbeck Jun 16, 2017

ddbeck Jun 16, 2017

theacodes Jun 16, 2017

ddbeck Jun 16, 2017

ddbeck Jun 16, 2017

ddbeck Jun 16, 2017

theacodes Jun 16, 2017

ddbeck Jun 16, 2017

theacodes Jun 16, 2017

ddbeck Jun 16, 2017

theacodes Jun 16, 2017

ddbeck Jun 16, 2017

theacodes commented Jun 16, 2017

ncoghlan commented Jun 17, 2017

ncoghlan commented Jun 17, 2017

theacodes commented Jun 17, 2017 via email

ncoghlan commented Jun 17, 2017


		Additionally, there is a list of :doc:`other projects <key_projects>` maintained by members of the Python Packaging Authority.

		Index


		If you want to learn how to package and distribute your projects, see the :doc:`tutorial on packaging and distributing <tutorials/distributing-packages>`

		More resources

Update landing page #326

Update landing page #326

Conversation

theacodes commented Jun 15, 2017

theacodes commented Jun 15, 2017

ncoghlan left a comment

Choose a reason for hiding this comment

ncoghlan commented Jun 16, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

theacodes commented Jun 16, 2017

ncoghlan commented Jun 17, 2017

Get Started

ncoghlan commented Jun 17, 2017

theacodes commented Jun 17, 2017 via email

ncoghlan commented Jun 17, 2017