rework directory hierarchy

README.md

@@ -18,18 +18,50 @@ of the stub files.
 
 ## Directory structure
 
+### Builtins vs stdlib
+
+Python ships with a set of built-in modules, i.e., modules that are baked into
+the Python executable. For a specific Python build, you can use
+`sys.builtin_module_names` to query which modules are built in. Also, you
+can determine whether a module is a built-in module by doing
+`import module; import.__file__`. If `__file__` exists, the module is not
+built in. Typeshed stores built-in modules in the "builtins/" directory.
+Examples for built-in modules: sys, array, math, signal.
+
+There are other modules that ship with Python, but are not linked into the
+Python binary. E.g. os.py, glob.py, zipfile.py. (But also some C extensions
+like datetime)
+These modules are stored in the stdlib/ directory.
+
+Note that built-in modules have higher precedence in the import path than stdlib
+modules.  The former are implicitly prepended to the start of your PYTHONPATH,
+whereas the latter are implicitly appended to it.
+
+### Version numbers
+
 We store stubs for both Python 2 as well as Python 3. We also distinguish
 between minor versions (E.g. 3.2 <-> 3.3). To accomplish not having to duplicate
 modules that are the same between all minor versions, we have e.g. a top-level
 directory 3/ that contains all the stubs for Python 3. More specialized stubs
 go into e.g. 3.3/ and supersede the more generic stubs in 3/. (And, if needed,
-a directory 3.3.1/ would be able to supersede stubs in 3.3/):
+a directory 3.3.1/ would be able to supersede stubs in 3.3/).
+Modules that are the same under both Python 2 and Python 3 go into 2and3/.
 
-Directory     | Contents
-------------- | -------------
-2.7/          | Stubs for Python 2.7
-3/            | Stubs for Python 3
-3.3/          | Some specialized stubs for Python 3.3 (replacing generic stubs in 3/)
+### Example
+
+Directory       | Contents
+-------------   | -------------
+builtins/2and3/ | Builtin stubs for Python 2 and Python 3
+builtins/2/     | Builtin stubs for Python 2
+...             | ...
+builtins/2.7/   | Builtin stubs for Python 2.7
+builtins/3/     | Builtin stubs for Python 3
+...             | ...
+builtins/3.3/   | Builtin stubs for Python 3.3 (replacing generic stubs in 3/)
+stdlib/2and3/   | Standard library stubs for Python 2 and Python 3
+stdlib/2.7/     | Standard library stubs for Python 2.7
+...             | ...
+stdlib/2.7.6/   | Standard library stubs specialized for Python 2.7.6
 
 ## Example
 
@@ -55,19 +87,6 @@ class date(object):
     def weekday(self) -> int: ...
 ```
 
-## About builtins vs stdlib
-
-C extensions that are built into Python (E.g. sys, array, math, signal, ...) have
-higher precedence in the import path than modules that ship with Python but
-are not built into the python binary (like os.py, glob.py, zipfile.py etc.;
-but also some C extensions like datetime). The
-former are implicitly prepended to the start of your PYTHONPATH, whereas the
-latter are implicitly appended to it.
-
-Typeshed doesn't explicitly distinguish between the two module types. For a specific
-Python build, you can use `sys.builtin_module_names` to query which modules 
-are built in and set import priority accordingly.
-
 ## Contributions
 
 We're welcoming contributions (pull requests) for types of third party