update docs388-failed-url

2 files changed, 20 insertions, 19 deletions

diff --git a/docs/source/acks.rst b/docs/source/acks.rst
index ceffe06..036b795 100644
--- a/docs/source/acks.rst
+++ b/docs/source/acks.rst
@@ -1,7 +1,7 @@
 Acknowledgements
 ################
 
-caveats
+Caveats
 =======
 
 ``forcing_headers`` + ``Content-Length``
@@ -11,7 +11,7 @@ When using the ``forcing_headers`` option make sure to add the header
 ``Content-Length`` otherwise calls using :py:mod:`requests` will try
 to load the response endlessly.
 
-supported libraries
+Supported Libraries
 -------------------
 
 Because HTTPretty works in the socket level it should work with any HTTP client libraries, although it is `battle tested <https://github.com/gabrielfalcao/HTTPretty/tree/master/tests/functional>`_ against:
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
index 53ef73f..a5339d2 100644
--- a/docs/source/introduction.rst
+++ b/docs/source/introduction.rst
@@ -39,8 +39,13 @@ Don't worry, HTTPretty is here for you:
 A more technical description
 ============================
 
-HTTPretty is a HTTP client mock library for Python 100% inspired on ruby's [FakeWeb](http://fakeweb.rubyforge.org/).
-If you come from ruby this would probably sound familiar :smiley:
+HTTPretty is a python library that swaps the modules :py:mod:`socket`
+and :py:mod:`ssl` with fake implementations that intercept HTTP
+requests at the level of a TCP connection.
+
+It is inspired on Ruby's `FakeWeb <http://fakeweb.rubyforge.org/>`_.
+
+If you come from the Ruby programming language this would probably sound familiar :smiley:
 
 Installing
 ==========
@@ -162,20 +167,16 @@ problem:
 
     *"I'm gonna need to mock all those requests"*
 
-It brings a lot of hassle, you will need to use a generic mocking
-tool, mess with scope and so on.
-
-The idea behind HTTPretty (how it works)
-========================================
-
-
-HTTPretty `monkey patches <http://en.wikipedia.org/wiki/Monkey_patch>`_
-Python's `socket <http://docs.python.org/library/socket.html>`_ core
-module, reimplementing the HTTP protocol, by mocking requests and
-responses.
+It can be a bit of a hassle to use something like
+:py:class:`mock.Mock` to stub the requests, this can work well for
+low-level unit tests but when writing functional or integration tests
+we should be able to allow the http calls to go through the TCP socket
+module.
 
-As for how it works this way, you don't need to worry what http
-library you're gonna use.
+HTTPretty `monkey patches
+<http://en.wikipedia.org/wiki/Monkey_patch>`_ Python's
+:py:mod:`socket` core module with a fake version of the module.
 
-HTTPretty will mock the response for you :) *(and also give you the
-latest requests so that you can check them)*
+Because HTTPretty implements a fake the modules :py:mod:`socket` and
+:py:mod:`ssl` you can use write tests to code against any HTTP library
+that use those modules.