Update documentation to better reflect new directory structure. (#4976)

See #2491 for previous discussion.

Co-authored-by: Ivan Levkivskyi <ilevkivskyi@dropbox.com>

README.md

@@ -23,27 +23,20 @@ Typeshed supports Python versions 2.7 and 3.6 and up.
 
 If you're just using mypy (or pytype or PyCharm), as opposed to
 developing it, you don't need to interact with the typeshed repo at
-all: a copy of typeshed is bundled with mypy.
+all: a copy of standard library part of typeshed is bundled with mypy.
+And type stubs for third party packages and modules you are using can
+be installed from PyPI. For example, if you are using `six` and `requests`,
+you can install the type stubs using
 
-When you use a checked-out clone of the mypy repo, a copy of typeshed
-should be included as a submodule, using
+    $ pip install types-six types-requests
 
-    $ git clone --recurse-submodules https://github.com/python/mypy.git
+These PyPI packages follow [PEP 561](http://www.python.org/dev/peps/pep-0561/)
+and are automatically generated by typeshed internal machinery. Also starting
+from version 0.900 mypy will provide an option to automatically install missing
+type stub packages (if found on PyPI).
 
-or
-
-    $ git clone https://github.com/python/mypy.git
-    $ cd mypy
-    $ git submodule init
-    $ git submodule update
-
-and occasionally you will have to repeat the final command (`git
-submodule update`) to pull in changes made in the upstream typeshed
-repo.
-
-PyCharm and pytype similarly include a copy of typeshed.  The one in
-pytype can be updated in the same way if you are working with the
-pytype repo.
+PyCharm, pytype etc. work in a similar way, for more details see documentation
+for the type-checking tool you are using.
 
 ## Format
 
@@ -63,16 +56,31 @@ coding style used in typeshed.
 
 ### stdlib
 
-This contains stubs for modules the Python standard library -- which
+This contains stubs for modules in the Python standard library -- which
 includes pure Python modules, dynamically loaded extension modules,
-hard-linked extension modules, and the builtins.
+hard-linked extension modules, and the builtins. `VERSIONS` file lists
+the oldest *supported* Python version where the module is available.
+In the `stdlib/@python2` subdirectory you can find Python 2 versions of
+the stub files that must be kept different for Python 2 and 3, like
+`builtins.pyi`.
 
-### third_party
+### stubs
 
 Modules that are not shipped with Python but have a type description in Python
-go into `third_party`. Since these modules can behave differently for different
-versions of Python, `third_party` has version subdirectories, just like
-`stdlib`.
+go into `stubs`. Each subdirectory there represents a PyPI distribution, and
+contains the following:
+* `METADATA.toml` that specifies oldest version of the source library for
+  which the stubs are applicable, supported Python versions (Python 3 defaults
+  to `True`, Python 2 defaults to `False`), and dependency on other type stub
+  packages.
+* Stubs (i.e. `*.pyi` files) for packages and modules that are shipped in the
+  source distribution. Similar to standard library, if the Python 2 version of
+  the stubs must be kept *separate*, it can be put in a `@python` subdirectory.
+* (Rarely) some docs specific to a given type stub package in `README` file.
+
+No other files are allowed in `stdlib` and `stubs`. When a third party stub is
+modified, an updated version of the corresponding distribution will be
+automatically uploaded to PyPI shortly (within few hours).
 
 For more information on directory structure and stub versioning, see
 [the relevant section of CONTRIBUTING.md](
@@ -87,8 +95,8 @@ following criteria is met:
 
 ## Contributing
 
-Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting pull
-requests. If you have questions related to contributing, drop by the [typing Gitter](https://gitter.im/python/typing).
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting pull requests.
+If you have questions related to contributing, drop by the [typing Gitter](https://gitter.im/python/typing).
 
 ## Running the tests