Add architectural assumptions

docs/contributing.rst

@@ -91,18 +91,38 @@ Architectural overview
 ----------------------
 
 Twine is a command-line tool for interacting with PyPI securely over
-HTTPS. Its command line arguments are parsed in
-:file:`twine/cli.py`. Currently, twine has two principal functions:
-uploading new packages and registering new `projects`_. The code for
-registering new projects is in :file:`twine/commands/register.py`, and
-the code for uploading is in :file:`twine/commands/upload.py`. The
-file :file:`twine/package.py` contains a single class,
-``PackageFile``, which hashes the project files and extracts their
-metadata. The file :file:`twine/repository.py` contains the
-``Repository`` class, whose methods control the URL the package is
-uploaded to (which the user can specify either as a default, in the
-:file:`.pypirc` file, or pass on the command line), and the methods
-that upload the package securely to a URL.
+HTTPS. Its three purposes are to be:
+
+1. A user-facing tool for publishing on pypi.org
+2. A user-facing tool for publishing on other Python package indexes
+   (e.g., ``devpi`` instances)
+3. A useful API for other programs (e.g., ``zest.releaser``) to call
+   for publishing on any Python package index
+
+
+Currently, twine has two principal functions: uploading new packages
+and registering new `projects`_ (``register`` is no longer supported
+on PyPI, and is in Twine for use with other package indexes).
+
+Its command line arguments are parsed in :file:`twine/cli.py`. The
+code for registering new projects is in
+:file:`twine/commands/register.py`, and the code for uploading is in
+:file:`twine/commands/upload.py`. The file :file:`twine/package.py`
+contains a single class, ``PackageFile``, which hashes the project
+files and extracts their metadata. The file
+:file:`twine/repository.py` contains the ``Repository`` class, whose
+methods control the URL the package is uploaded to (which the user can
+specify either as a default, in the :file:`.pypirc` file, or pass on
+the command line), and the methods that upload the package securely to
+a URL.
+
+Where Twine gets configuration and credentials
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A user can set the repository URL, username, and/or password via
+command line, ``.pypirc`` files, environment variables, and
+``keyring``.
+
 
 Adding a maintainer
 -------------------