Skip to content

Commit 356dabd

Browse files
willingcpradyunsg
authored andcommitted
Add prose for readability
1 parent c1abfc2 commit 356dabd

File tree

1 file changed

+41
-27
lines changed

1 file changed

+41
-27
lines changed

source/index.rst

Lines changed: 41 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -27,53 +27,67 @@ references to help you distribute and install Python packages with modern
2727
tools.
2828

2929
This guide is maintained on `GitHub`_ by the :doc:`Python Packaging Authority <pypa:index>`. We
30-
happily accept any :doc:`contributions and feedback <contribute>`. 😊
30+
happily accept :doc:`contributions and feedback <contribute>`. 😊
3131

3232
.. _GitHub: https://github.com/pypa/packaging.python.org
3333

3434

35-
Overview
36-
========
35+
Overview and Flow
36+
=================
3737

38-
* To get an overview of packaging options for Python libraries and
39-
applications, see the :doc:`Overview of Python Packaging <overview>`
38+
.. note::
39+
40+
Building your understanding of Python packaging is a journey. Patience and
41+
continuous improvement are key to success. The overview and flow sections
42+
provide a starting point for understanding the Python packaging ecosystem.
43+
44+
The :doc:`Overview of Python Packaging <overview>` explains Python packaging
45+
and its use when preparing and distributing projects.
46+
This section helps you build understanding about selecting the tools and
47+
processes that are most suitable for your use case.
48+
It includes what packaging is, the problems that it solves, and
49+
key considerations.
50+
51+
To get an overview of the workflow used to publish your code, see
52+
:doc:`packaging flow <flow>`.
4053

4154
Tutorials
4255
=========
4356

44-
Essential tools and concepts for working within the Python
45-
development ecosystem are covered in our :doc:`tutorials/index` section.
57+
Tutorials walk through the steps needed to complete a project for the first time.
58+
Tutorials aim to help you succeed and provide a starting point for future
59+
exploration.
60+
The :doc:`tutorials/index` section includes:
4661

47-
* To learn how to install packages, see the
48-
:doc:`tutorial on installing packages <tutorials/installing-packages>`
49-
* To learn how to manage dependencies in a version controlled project, see the
50-
:doc:`tutorial on managing application dependencies <tutorials/managing-dependencies>`
51-
* To learn how to package and distribute your projects, see the
52-
:doc:`tutorial on packaging and distributing <tutorials/packaging-projects>`
62+
* A :doc:`tutorial on installing packages <tutorials/installing-packages>`
63+
* A :doc:`tutorial on managing application dependencies <tutorials/managing-dependencies>`
64+
in a version controlled project
65+
* A :doc:`tutorial on packaging and distributing <tutorials/packaging-projects>`
66+
your project
5367

5468
Guides
5569
======
5670

57-
* The :doc:`guides/index` section for walk throughs, such as
58-
:doc:`guides/installing-using-linux-tools` or :doc:`guides/packaging-binary-extensions`.
71+
Guides provide steps to perform a specific task. Guides are more focused on
72+
users who are already familiar with Python packaging and are looking for
73+
specific information.
74+
75+
The :doc:`guides/index` section provides "how to" instructions in three major
76+
areas: package installation; building and distributing packages; miscellaneous
77+
topics.
5978

6079
Explanations and Discussions
6180
============================
6281

63-
* To get an overview of the flow used to publish your code, see the
64-
:doc:`packaging flow <flow>`
65-
* The :doc:`discussions/index` section for in-depth references on topics such as
66-
:doc:`discussions/deploying-python-applications` or :doc:`discussions/pip-vs-easy-install`.
82+
The :doc:`discussions/index` section for in-depth explanations and discussion
83+
about topics, such as:
84+
85+
* :doc:`discussions/deploying-python-applications`
86+
* :doc:`discussions/pip-vs-easy-install`
6787

6888
Reference
6989
=========
7090

7191
* The :doc:`specifications/index` section for packaging interoperability specifications.
72-
* Additionally, there is a list of :doc:`other projects <key_projects>` maintained
73-
by members of the Python Packaging Authority.
74-
75-
Get started
76-
===========
77-
78-
79-
92+
* The list of :doc:`other projects <key_projects>` maintained by members of the Python Packaging Authority.
93+
* The :doc:`glossary` for definitions of terms used in Python packaging.

0 commit comments

Comments
 (0)