realpython · kennethreitz · Jan 26, 2013 · Jan 26, 2013
diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
@@ -1,118 +1,119 @@
-Getting Started
----------------
-
-This part of the guide focuses on setting up your Python environment.
-
-.. toctree::
-   :maxdepth: 2
-
-   starting/which-python
-
-- Properly Install Python
-
- .. toctree::
-    :maxdepth: 1
-
-    starting/install/osx
-    starting/install/win
-    starting/install/linux
-
-
-
-Writing Great Code
-------------------
-
-This part of the guide focuses on best practices for writing Python code.
-
-.. toctree::
-   :maxdepth: 2
-
-   writing/structure
-   writing/style
-   writing/documentation
-   writing/tests
-   writing/gotchas
-   writing/license
-
-
-
-Scenario Guide
---------------
-
-This part of the guide focuses on tool and module advice based on
-different scenarios.
-
-.. toctree::
-   :maxdepth: 2
-
-   scenarios/client
-   scenarios/web
-   scenarios/cli
-   scenarios/gui
-   scenarios/db
-   scenarios/network
-   scenarios/admin
-   scenarios/ci
-   scenarios/speed
-   scenarios/scientific
-   scenarios/imaging
-   scenarios/xml
-
-
-Shipping Great Code
--------------------
-
-This part of the guide focuses on deploying your Python code.
-
-.. toctree::
-   :maxdepth: 2
-
-   shipping/packaging
-   shipping/freezing
-
-
-Development Environment
------------------------
-
-.. toctree::
-   :maxdepth: 2
-
-   dev/env
-   dev/virtualenvs
-
-
-
-
-Additional Notes
-----------------
-
-This part of the guide, which is mostly prose, begins with some
-background information about Python, then focuses on next steps.
-
-.. toctree::
-   :maxdepth: 2
-
-   intro/duction
-   intro/community
-   intro/learning
-   intro/documentation
-   intro/news
-
-
-
-
---------------------------------------
-
-Contribution notes and legal information are here (for those interested).
-
-.. toctree::
-   :maxdepth: 2
-
-   notes/contribute
-   notes/license
-   notes/styleguide
-
-
-
-
-
+Getting Started
+---------------
+
+This part of the guide focuses on setting up your Python environment.
+
+.. toctree::
+   :maxdepth: 2
+
+   starting/which-python
+
+- Properly Install Python
+
+ .. toctree::
+    :maxdepth: 1
+
+    starting/install/osx
+    starting/install/win
+    starting/install/linux
+
+
+
+Writing Great Code
+------------------
+
+This part of the guide focuses on best practices for writing Python code.
+
+.. toctree::
+   :maxdepth: 2
+
+   writing/structure
+   writing/style
+   writing/reading
+   writing/documentation
+   writing/tests
+   writing/gotchas
+   writing/license
+
+
+
+Scenario Guide
+--------------
+
+This part of the guide focuses on tool and module advice based on
+different scenarios.
+
+.. toctree::
+   :maxdepth: 2
+
+   scenarios/client
+   scenarios/web
+   scenarios/cli
+   scenarios/gui
+   scenarios/db
+   scenarios/network
+   scenarios/admin
+   scenarios/ci
+   scenarios/speed
+   scenarios/scientific
+   scenarios/imaging
+   scenarios/xml
+
+
+Shipping Great Code
+-------------------
+
+This part of the guide focuses on deploying your Python code.
+
+.. toctree::
+   :maxdepth: 2
+
+   shipping/packaging
+   shipping/freezing
+
+
+Development Environment
+-----------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   dev/env
+   dev/virtualenvs
+
+
+
+
+Additional Notes
+----------------
+
+This part of the guide, which is mostly prose, begins with some
+background information about Python, then focuses on next steps.
+
+.. toctree::
+   :maxdepth: 2
+
+   intro/duction
+   intro/community
+   intro/learning
+   intro/documentation
+   intro/news
+
+
+
+
+--------------------------------------
+
+Contribution notes and legal information are here (for those interested).
+
+.. toctree::
+   :maxdepth: 2
+
+   notes/contribute
+   notes/license
+   notes/styleguide
+
+
+
+
+
diff --git a/docs/writing/reading.rst b/docs/writing/reading.rst
@@ -0,0 +1,44 @@
+Reading Great Code
+==================
+
+One of the core tenants behind the design of Python is creating
+readable code. The motivation behind this design is simple: The number 
+one thing that Python programmers do is read code. 
+
+One of the secrets of becoming a great Python programmer is to read, 
+understand, and comprehend excellent code.
+
+Excellent code typically follows the guidelines outlined in :ref:`code_style`,
+and does its best to express a clear and consise intent to the reader.
+
+Included below is a list of recommended Python projects for reading. Each of
+these projects are paragons of excellent Python code.
+
+- `Howdoi <https://github.com/gleitz/howdoi>`_
+  Howdoi is a code search tool, written in Python.
+
+- `Flask <https://github.com/mitsuhiko/flask>`_
+  Flask is a microframework for Python based on Werkzeug and Jinja2. 
+  It's intended for getting started very quickly and was developed with 
+  best intentions in mind.
+
+- `Werkzeug <https://github.com/mitsuhiko/werkzeug>`_
+  Werkzeug started as simple collection of various utilities for WSGI
+  applications and has become one of the most advanced WSGI utility modules.
+  It includes a powerful debugger, full-featured request and response objects,
+  HTTP utilities to handle entity tags, cache control headers, HTTP dates,
+  cookie handling, file uploads, a powerful URL routing system and a bunch
+  of community-contributed addon modules.
+
+- `Requests <https://github.com/kennethreitz/requests>`_
+  Requests is an Apache2 Licensed HTTP library, written in Python,
+  for human beings.
+
+- `Tablib <https://github.com/kennethreitz/tablib>`_
+  Tablib is a format-agnostic tabular dataset library, written in Python.
+
+.. todo:: Embed and explain YouTube video showing python code reading: http://www.youtube.com/watch?v=Jc8M9-LoEuo This may require installing a Sphinx plugin. https://bitbucket.org/birkenfeld/sphinx-contrib/src/a09f29fc16970f34350ca36ac7f229e00b1b1674/youtube?at=default
+
+.. todo:: Include code examples of exemplary code from each of the projects listed. Explain why it is excellent code. Use complex examples.
+
+.. todo:: Explain techniques to rapidly identify data structures, algorithms and determine what the code is doing.