Move Usage Modes here

Working-with-Updates.md

@@ -0,0 +1,51 @@
+There are two ways in which you may want to use the library. Some people will simply want to show information about updates as they come, or invoke other requests as certain events happen, while other people don't care about processing updates at all. A mix between all of these is also possible.
+
+## Listening for updates
+
+By default, the library won't process updates at all (while it will still send periodic pings to ensure that the connection stays alive). If you want to listen for updates, simply add a new handler:
+
+```python
+def my_handler(update_object):
+    print('I received an update:', update_object)
+
+client.add_update_handler(my_handler)
+
+# You can also remove the handler at a later point:
+client.remove_update_handler(my_handler)
+
+# Or see which handlers are currently added:
+# handlers = client.list_update_handlers()
+```
+
+An update handler is nothing else than a method accepting a single parameter, the update object to be processed.
+
+Updates will be processed as long as there is at least one handler added, and adding the first handler will trigger a forced synchronization of the update state (manually called through `client.sync_updates()`)
+
+**You cannot invoke requests from within these handlers**. The handlers are called from a **read-only thread**, and attempting to invoke a request (hence sending it) will raise an `AssertionError`.
+
+## Reacting to updates
+
+In order to invoke some request upon receiving an update, you need your own thread. If all you need is to react to updates, you may just use the main thread instead creating a new one.
+
+The first step is to tell the `TelegramClient` that we will be actively polling new updates:
+
+```python
+client = TelegramClient('myself', api_id, api_hash, process_updates=True)
+
+# Or, if you already have a client
+client.updates.polling = True
+```
+
+Setting this flag to `True` will also cause the library to process updates, even if no `update_handler` was added. You should generally prefer this if you're going to only have a handler, and the main thread has no other job to do.
+
+Now, you **must** poll updates, or your memory will eventually fill. On your thread (or simply on the main thread) do:
+
+```python
+while True:
+    # A call to .poll() will block until there's an update available
+    update = client.updates.poll()
+
+    # Here you can invoke requests with the client and use the update
+    # For instance, we can send a message to ourselves
+    client.send_message(myself, 'New update {}'.format(update))
+```

Working-with-updates.md

@@ -1,22 +0,0 @@
-**Important note**: Updates are currently handled in a **passive** way, so **not all may be received**. Read below for more information.
-
----
-
-The most minimal example to receive updates, and often what you will need if processing updates is all you need, is as follows:
-```python
-def update_handler(update_object):
-    # On this example, we just show the update object itself
-    print(update_object)
-
-
-# From now on, any update received will be passed to 'update_handler'
-client.add_update_handler(update_handler)
-
-input('Press <ENTER> to exit...')
-client.disconnect()
-```
-
-The `update_object` may be any instance of [`Updates`](https://lonamiwebs.github.io/Telethon/types/updates.html) or even a single [`Update`](https://lonamiwebs.github.io/Telethon/types/update.html), so you have absolute control about which updates you want to handle and which you don't. `isinstance(update_object, SomeClass)` may prove very useful here.
-
-## Note follow-up
-The library currently handles all updates in a **passive** way, so not all updates may be received. This is, all it does is listen to what the server sends. It will **not** run things like [`GetDifferenceRequest`](https://lonamiwebs.github.io/Telethon/methods/updates/get_difference.html) or take into consideration the methods that return more [`Updates`](https://lonamiwebs.github.io/Telethon/types/updates.html).