[2/5] docs: Rework XML-RPC docs

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
diff --git a/docs/usage/xmlrpc.md b/docs/usage/xmlrpc.md
new file mode 100644
index 0000000..de95a07
--- /dev/null
+++ b/docs/usage/xmlrpc.md
@@ -0,0 +1,37 @@ 
+# The XML-RPC API
+
+**NOTE:** This guide covers usage information for the Patchwork XML-RPC API.
+For information on developing custom applications or clients for this API,
+refer to the [developers documentation][doc-development].
+
+Patchwork provides an XML-RPC API. This API can be used to be used to retrieve
+and modify information about patches, projects and more.
+
+**NOTE:** The XML-RPC API can be enabled/disabled by the administrator: it may
+not be available in every instance.
+
+## pwclient
+
+The `pwclient` application, provided with Patchwork, can be used to interact
+with Patchwork from the command line. Functionality provided by `pwclient`
+includes:
+
+* Listing patches, projects, and checks
+* Downloading and applying patches to a local code base
+* Modifying the status of patches
+* Creating new checks
+
+pwclient can be downloaded from the [Ozlabs Patchwork instance][ref-pw-oz], or
+at the following path for other Patchwork instances:
+
+    http://patchwork.example.com/pwclient/
+
+where `patchwork.example.com` corresponds to the URL a Patchwork instance is
+hosted at.
+
+Once downloaded, to view information about all the operations supported by
+`pwclient`, run:
+
+    $ pwclient --help
+
+[doc-development]: ../development/xmlrpc.md
diff --git a/mkdocs.yml b/mkdocs.yml
index 0bbe7e1..5980ac9 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -14,3 +14,5 @@  pages:
  - Deployment Guide:
    - Installation: 'deployment/installation.md'
    - Upgrading: 'deployment/upgrading.md'
+ - Usage Guide:
+   - XML-RPC API: 'usage/xmlrpc.md'