Major docs update

Paul Hallett · Paul Hallett · commit d60508b226f5 · 2014-08-10T17:53:32.000+01:00
diff --git a/docs/usage/caller-ids.rst b/docs/usage/caller-ids.rst
@@ -8,7 +8,7 @@ Caller Ids
 Validate a Phone Number
 -----------------------
 
-Validating a phone number is quick and easy.
+Validating a phone number can be done with the Python helper library, the code block below provides a simple example.
 
 .. code-block:: python
 
@@ -19,7 +19,7 @@ Validating a phone number is quick and easy.
     AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
 
     client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
-    response = client.caller_ids.validate("+44 9876543212")
+    response = client.caller_ids.validate("+449876543212")
     print response.validation_code
 
 Twilio will call the provided number and wait for the validation code to be
@@ -28,12 +28,12 @@ entered.
 Delete a Phone Number
 ---------------------
 
-Deleting a phone number is quick and easy.
+Deleting a validated phone number is just as easy as validating.
 
 .. code-block:: python
 
     from twilio.rest import TwilioRestClient
-    
+
     # To find these visit https://www.twilio.com/user/account
     account = "ACXXXXXXXXXXXXXXXXX"
     token = "YYYYYYYYYYYYYYYYYY"
diff --git a/docs/usage/conferences.rst b/docs/usage/conferences.rst
@@ -4,6 +4,7 @@
 Conferences and Participants
 ==============================
 
+The :class:`Conference` resource manages all interaction with Twilio conferences, such as listing and managing participants.
 For more information, see the `Conference REST Resource <http://www.twilio.com/docs/api/rest/conference>`_ and `Participant REST Resource <http://www.twilio.com/docs/api/rest/participant>`_ documentation.
 
 
diff --git a/docs/usage/messages.rst b/docs/usage/messages.rst
@@ -4,15 +4,15 @@
 Messages
 ============
 
-For more information, see the
-`SMS Message REST Resource <http://www.twilio.com/docs/api/rest/sms>`_
+The :class:`Messages` resource manages all interaction with Twilio SMS and MMS messages. For more information, see the
+`Message REST Resource <http://www.twilio.com/docs/api/rest/message>`_
 documentation.
 
 
 Sending a Text Message
 ----------------------
 
-Send a text message in only a few lines of code.
+The :class:`Message` resource allows you to send an SMS message in a few lines of code.
 
 .. code-block:: python
 
@@ -40,7 +40,7 @@ to your short code's number.
 Sending a Picture Message
 -------------------------
 
-To send a picture, set :attr:`media_url` to the url of the picture you wish to send.
+To send a picture message (MMS), set :attr:`media_url` to the url of the picture you wish to send.
 
 .. code-block:: python
 
diff --git a/docs/usage/notifications.rst b/docs/usage/notifications.rst
@@ -4,6 +4,7 @@
 Notifications
 ====================
 
+A :class:`Notification` resource represents a single log entry made by Twilio in the course of handling your calls or your use of the REST API.
 For more information, see the `Notifications REST Resource
 <http://www.twilio.com/docs/api/rest/notification>`_ documentation.
 
diff --git a/docs/usage/phone-calls.rst b/docs/usage/phone-calls.rst
@@ -5,15 +5,16 @@ Phone Calls
 =====================
 
 The :class:`Calls` resource manages all interaction with Twilio phone calls,
-including the creation and termination of phone calls.
+including the creation and termination of phone calls. For more information, see the `Calls REST Resource <http://www.twilio.com/docs/api/rest/call>`_
+documentation.
 
 
 Making a Phone Call
 -------------------
 
 The :class:`Calls` resource allows you to make outgoing calls. Before a call
 can be successfully started, you'll need a to set up a url endpoint which
-outputs valid `TwiML <http://www.twilio.com/docs/api/twiml/>`_.
+outputs valid `TwiML <http://www.twilio.com/docs/api/twiml/>`_. This can be done with the :class: `twiml.Response` class, `get started here <http://twilio-python.readthedocs.org/en/latest/usage/twiml.html#twiml-creation>`_.
 
 .. code-block:: python
 
diff --git a/docs/usage/phone-numbers.rst b/docs/usage/phone-numbers.rst
@@ -4,7 +4,7 @@
 Phone Numbers
 =================
 
-With Twilio you can search and buy real phone numbers, just using the API.
+With Twilio you can search and buy real phone numbers using the API.
 
 For more information, see the
 `IncomingPhoneNumbers REST Resource
@@ -15,7 +15,7 @@ Searching and Buying a Number
 --------------------------------
 
 Finding numbers to buy couldn't be easier.
-We first search for a number in area code 530.
+The example below searches for a number with US area code '530'.
 Once we find one, we'll purchase it for our account.
 
 .. code-block:: python
@@ -137,7 +137,7 @@ shown in the first example).
 Updating Properties on a Number
 -------------------------------
 
-To update the properties on a phone number, call :meth:`update`
+To update the properties on a phone number, such as the Voice URL, call :meth:`update`
 on the phone number object, with any of the parameters
 listed in the `IncomingPhoneNumbers Resource documentation
 <http://www.twilio.com/docs/api/rest/incoming-phone-numbers>`_
@@ -152,8 +152,8 @@ listed in the `IncomingPhoneNumbers Resource documentation
 
     client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
     for number in client.phone_numbers.list(api_version="2010-04-01"):
-        number.update(voice_url="http://twimlets.com/holdmusic?" + 
-            "Bucket=com.twilio.music.ambient", 
+        number.update(voice_url="http://twimlets.com/holdmusic?" +
+            "Bucket=com.twilio.music.ambient",
             status_callback="http://example.com/callback")
 
 
diff --git a/docs/usage/queues.rst b/docs/usage/queues.rst
@@ -4,10 +4,9 @@
 Queues and Members
 ==============================
 
-For more information, see the
-`Queue REST Resource <http://www.twilio.com/docs/api/rest/queue>`_
-and `Member REST Resource <http://www.twilio.com/docs/api/rest/member>`_
-documentation.
+The :class:`Queue` resource allows you to query and manage the state of individual call queues.For more information, see the `Queue REST Resource <http://www.twilio.com/docs/api/rest/queue>`_.
+
+The :class:`Members` resource is a subresource of a Queue resource. It represents the set of members currently in a queue. See the `Member REST Resource <http://www.twilio.com/docs/api/rest/member>`_ documentation for more information.
 
 
 Listing Queues
diff --git a/docs/usage/recordings.rst b/docs/usage/recordings.rst
@@ -3,7 +3,7 @@
 ================
 Recordings
 ================
-
+A :class:`Recording` resource represents an individually recorded call. Recordings are generated when you use the `Record <https://www.twilio.com/docs/api/twiml/record>`_ TwiML verb.
 For more information, see the
 `Recordings REST Resource <http://www.twilio.com/docs/api/rest/recording>`_
 documentation.
diff --git a/docs/usage/sip.rst b/docs/usage/sip.rst
@@ -5,15 +5,15 @@ Sip In
 Getting started with Sip
 ==========================
 
-If you're unfamiliar with SIP, please see the `SIP API Documentation
-<https://www.twilio.com/docs/api/rest/sip>`_ on our website.
+Connect your SIP endpoints to Twilio and start building voice apps with Twilio’s APIs and application stack. If you're unfamiliar with SIP, please see the `SIP API Documentation <https://www.twilio.com/docs/api/rest/sip>`_ on our website.
 
 Creating a Sip Domain
 =========================
 
 The :class:`Domains` resource allows you to create a new domain. To
 create a new domain, you'll need to choose a unique domain that lives
 under sip.twilio.com. For example, dunder-mifflin-scranton.sip.twilio.com.
+For more information, see the `Domains resource documentation <https://www.twilio.com/docs/api/rest/domain>`_ on our website.
 
 .. code-block:: python
 
diff --git a/docs/usage/transcriptions.rst b/docs/usage/transcriptions.rst
@@ -4,6 +4,7 @@
 Transcriptions
 ================
 
+A :class:`Transcription` resource represents a transcription of a recording. The transcription text itself is the result of converting an audio recording to readable text.
 Transcriptions are generated from recordings via the
 `TwiML <Record> verb <http://www.twilio.com/docs/api/twiml/record>`_.
 Using the API, you can only read your transcription records.
@@ -15,7 +16,7 @@ For more information, see the `Transcriptions REST Resource
 Listing Your Transcriptions
 ----------------------------
 
-The following code will print out the length of each :class:`Transcription`.
+The following code will print out the transcription text of each :class:`Transcription`.
 
 .. code-block:: python
 
@@ -27,5 +28,5 @@ The following code will print out the length of each :class:`Transcription`.
 
     client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
     for transcription in client.transcriptions.list():
-        print transcription.duration
+        print transcription.transcriptiontext
 
diff --git a/docs/usage/twiml.rst b/docs/usage/twiml.rst
@@ -13,6 +13,10 @@ These methods return the verbs they create to ease creation of nested TwiML.
 To finish, call the :meth:`toxml` method on the :class:`Response`,
 which returns raw TwiML.
 
+To get started with TwiML, read the `TwiML documentation <https://www.twilio.com/docs/api/twiml>`_ on our website.
+
+The following code block creates a simple TwiML Response.
+
 .. code-block:: python
 
     from twilio import twiml
@@ -21,6 +25,8 @@ which returns raw TwiML.
     r.say("Hello")
     print str(r)
 
+The output is perfectly formatted XML:
+
 .. code-block:: xml
 
    <?xml version="1.0" encoding="utf-8"?>
diff --git a/twilio/twiml.py b/twilio/twiml.py
@@ -1,5 +1,5 @@
 """
-Make sure to check out the TwiML overview and tutorial
+Make sure to check out the TwiML overview and tutorial at https://www.twilio.com/docs/api/twiml
 """
 import xml.etree.ElementTree as ET
 
