Update CONTRIBUTING.rst and README.rst

README.rst

@@ -1,5 +1,5 @@
-``fbchat``: Facebook Chat (Messenger) for Python
-================================================
+``fbchat`` - Facebook Messenger for Python
+==========================================
 
 .. image:: https://badgen.net/pypi/license/fbchat
     :target: https://github.com/carpedm20/fbchat/tree/master/LICENSE
@@ -25,13 +25,23 @@
     :target: https://github.com/ambv/black
     :alt: Code style
 
-Facebook Chat (`Messenger <https://www.facebook.com/messages/>`__) for Python.
-This project was inspired by `facebook-chat-api <https://github.com/Schmavery/facebook-chat-api>`__.
+A powerful and efficient library to interact with
+`Facebook\'s Messenger <https://www.facebook.com/messages/>`__, using just your email and password.
 
-**No XMPP or API key is needed**. Just use your email and password.
+This is *not* an official API, Facebook has that `over here <https://developers.facebook.com/docs/messenger-platform>`__ for chat bots. This library differs by using a normal Facebook account instead.
+
+``fbchat`` currently support:
+
+- Sending many types of messages, with files, stickers, mentions, etc.
+- Fetching all messages, threads and images in threads.
+- Searching for messages and threads.
+- Creating groups, setting the group emoji, changing nicknames, creating polls, etc.
+- Listening for, an reacting to events in real-time.
+- Type hints, and a modern codebase (e.g. only Python 3.5 and upwards).
+- ``async``/``await`` (COMING).
+
+Essentially, everything you need to make an amazing Facebook bot!
 
-Go to `Read the Docs <https://fbchat.readthedocs.io>`__ to see the full documentation,
-or jump right into the code by viewing the `examples <https://github.com/carpedm20/fbchat/tree/master/examples>`__
 
 Version warning:
 ----------------
@@ -39,23 +49,64 @@ Version warning:
 
 Additionally, you can view the project's progress `here <https://github.com/carpedm20/fbchat/projects/2>`__.
 
-Installation:
+
+Caveats
+-------
+
+``fbchat`` works by imitating what the browser does, and thereby tricking Facebook into thinking it's accessing the website normally.
+
+However, there's a catch! **Using this library may not comply with Facebook's Terms Of Service!**, so be responsible Facebook citizens! We are not responsible if your account gets banned!
+
+Additionally, **the APIs the library is calling is undocumented!** In theory, this means that your code could break tomorrow, without the slightest warning!
+If this happens to you, please report it, so that we can fix it as soon as possible!
+
+.. inclusion-marker-intro-end
+.. This message doesn't make sense in the docs at Read The Docs, so we exclude it
+
+With that out of the way, you may go to `Read The Docs <https://fbchat.readthedocs.io/>`__ to see the full documentation!
+
+.. inclusion-marker-installation-start
+
+
+Installation
+------------
+
+.. code-block:: sh
+
+    $ pip install fbchat
+
+If you don't have `pip <https://pip.pypa.io/>`_, `this guide <http://docs.python-guide.org/en/latest/starting/installation/>`_ can guide you through the process.
+
+You can also install directly from source, provided you have ``pip>=19.0``:
+
+.. code-block:: sh
+
+    $ pip install git+https://github.com/carpedm20/fbchat.git
+
+.. inclusion-marker-installation-end
+
+
+Example usage
 -------------
 
-.. code-block::
+.. code-block:: python
 
-    $ pip install fbchat
+    import getpass
+    import fbchat
+    session = fbchat.Session.login("<email/phone number>", getpass.getpass())
+    user = fbchat.User(session=session, id=session.user_id)
+    user.send_text("Test message!")
 
-You can also install from source if you have ``pip>=19.0``:
-
-.. code-block::
-
-    $ git clone https://github.com/carpedm20/fbchat.git
-    $ pip install fbchat
+More examples are available `here <https://github.com/carpedm20/fbchat/tree/master/examples>`__.
 
 
 Maintainer
 ----------
 
 - Mads Marquart / `@madsmtm <https://github.com/madsmtm>`__
-- Taehoon Kim / `@carpedm20 <http://carpedm20.github.io/about/>`__
+
+
+Acknowledgements
+----------------
+
+This project was originally inspired by `facebook-chat-api <https://github.com/Schmavery/facebook-chat-api>`__.