Document the breaking change with the new dictionary storage change.

Since the only things dict views support are iteration we should
advise people who want the old behaviour to change it to a list.

discord/client.py

@@ -88,9 +88,9 @@ class Client:
         Represents the current voice connection. None if you are not connected
         to a voice channel. To connect to voice use :meth:`join_voice_channel`.
         To query the voice connection state use :meth:`is_voice_connected`.
-    servers : list of :class:`Server`
+    servers : iterable of :class:`Server`
         The servers that the connected client is a member of.
-    private_channels : list of :class:`PrivateChannel`
+    private_channels : iterable of :class:`PrivateChannel`
         The private channels that the connected client is participating on.
     messages
         A deque_ of :class:`Message` that the client has received from all

discord/server.py

@@ -67,9 +67,9 @@ class Server(Hashable):
     afk_channel : :class:`Channel`
         The channel that denotes the AFK channel. None if it doesn't exist.
     members
-        A list of :class:`Member` that are currently on the server.
+        An iterable of :class:`Member` that are currently on the server.
     channels
-        A list of :class:`Channel` that are currently on the server.
+        An iterable of :class:`Channel` that are currently on the server.
     icon : str
         The server's icon.
     id : str

docs/migrating.rst

@@ -122,6 +122,43 @@ After:
 In order for you to ``yield from`` or ``await`` a coroutine then your function must be decorated
 with ``@asyncio.coroutine`` or ``async def``.
 
+.. _migrating-iterable:
+
+Iterables
+----------
+
+For performance reasons, many of the internal data structures were changed into a dictionary to support faster
+lookup. As a consequence, this meant that some lists that were exposed via the API have changed into iterables
+and not sequences. In short, this means that certain attributes now only support iteration and not any of the
+sequence functions.
+
+The affected attributes are as follows:
+
+- :attr:`Client.servers`
+- :attr:`Client.private_channels`
+- :attr:`Server.channels`
+- :attr:`Server.members`
+
+Some examples of previously valid behaviour that is now invalid
+
+.. code-block:: python
+
+    if client.servers[0].name == "test":
+        # do something
+
+Since they are no longer ``list``\s, they no longer support indexing or any operation other than iterating.
+In order to get the old behaviour you should explicitly cast it to a list.
+
+.. code-block:: python
+
+    servers = list(client.servers)
+    # work with servers
+
+.. warning::
+
+    Due to internal changes of the structure, the order you receive the data in
+    is not in a guaranteed order.
+
 .. _migrating-enums:
 
 Enumerators