1 files changed, 31 insertions, 30 deletions
diff --git a/docs/development/xmlrpc.md b/docs/development/xmlrpc.md
index cfa5acf..141dec9 100644
--- a/docs/development/xmlrpc.md
+++ b/docs/development/xmlrpc.md
@@ -1,5 +1,9 @@
 # The XML-RPC API
 
+**NOTE:** This guide covers development information for the Patchwork XML-RPC
+API. For general usage of the API, refer to the [usage
+documentation][doc-usage].
+
 Patchwork provides an XML-RPC API. This API can be used to be used to retrieve
 and modify information about patches, projects and more.
 
@@ -19,33 +23,30 @@ Where `patchwork.example.com` refers to the URL of your Patchwork instance.
 introduced in Patchwork v1.1. Prior versions of Patchwork do not offer this
 functionality.
 
-## Developing Your Own Client
-
-You need to connect to the server. Some methods require authentication (via
-HTTP Basic Auth) while others do not. Authentication uses your Patchwork
-account and the on-server documentation will indicate where it is necessary.
-We will only cover the unauthenticated method here for brevity - please
-consult the [`xmlrpclib`] documentation for more detailed examples:
-
-    from __future__ import print_function
-    import sys
-    import xmlrpclib
-
-    url = 'http://patchwork.example.org/xmlrpc/'
-
-    try:
-        rpc = xmlrpclib.ServerProxy(url)
-    except:
-        print('Unable to connect to %s\n' % url, file=sys.stderr)
-        sys.exit(1)
-
-After connecting, the `rpc` object will be populated with a list of available
-functions (or procedures, in RPC terminology). For example, if we continue
-with the above example:
-
-    print(rpc.pw_rpc_version())
-
-It should be possible to use all the methods listed in the
-[server's documentation](#patchwork-api-documentation).
-
-[`xmlrpclib`]: https://docs.python.org/2/library/xmlrpclib.html
+## Interacting with the API
+
+**NOTE:** The Patchwork XML-RPC API provides a number of "methods". Some
+methods require authentication (via HTTP Basic Auth) while others do not.
+Authentication uses your Patchwork account and the on-server documentation will
+indicate where it is necessary.  We will only cover the unauthenticated method
+here for brevity - please consult the [`xmlrpclib`][ref-xmlrpclib]
+documentation for more detailed examples:
+
+To interact with the Patchwork XML-RPC API, a XML-RPC library should be used.
+Python provides such a library - [`xmlrpclib`][ref-xmlrpclib] - in its standard
+library. For example, to get the version of the XML-RPC API for a Patchwork
+instance hosted at `patchwork.example.com`, run:
+
+    $ python
+    >>> import xmlrpclib  # or 'xmlrpc.client' for Python 3
+    >>> rpc = xmlrpclib.ServerProxy('http://patchwork.example.com/xmlrpc/')
+    >>> rpc.pw_rpc_version()
+    1.1
+
+Once connected, the `rpc` object will be populated with a list of available
+functions (or procedures, in RPC terminology). In the above example, we used
+the `pw_rpc_version` method, however, it should be possible to use all the
+methods listed in the [server documentation](#patchwork-api-documentation).
+
+[doc-usage]: ../usage/xmlrpc.md
+[ref-xmlrpclib]: https://docs.python.org/2/library/xmlrpclib.html