Update documentation

CONTRIBUTING.md

@@ -2,41 +2,40 @@
 
 Pull requests are welcome!
 
-Feel free to open an issue if you found a bug, have new ideas, suggestions or found a mistake
-in [documentation](https://python-telegram.readthedocs.io/en/latest/).
+Feel free to open an issue if you find a bug, have new ideas, suggestions, 
+or spot a mistake in the [documentation](https://python-telegram.readthedocs.io/en/latest/).
 
 ## Reporting bugs
 
 We use [GitHub
 Issues](https://github.com/alexander-akhmetov/python-telegram/issues) to track
-bugs. If you found a bug, please, open a new issue.
+bugs. If you find a bug, please open a new issue.
 
-Try to include steps to reproduce and detailed description of the bug and maybe
-some sample code.
+Try to include steps to reproduce the bug, a detailed description, and some sample code if possible.
 
 ## Pull request process
 
 1. Fork the repository and create a new branch from `master`.
-2. Make your changes and do not forget about new tests :)
+2. Make your changes and don't forget to add new tests :)
 3. Ensure the tests pass with your changes.
 4. Create a new PR!
 
 ## Coding style
 
-The project uses [black](https://github.com/psf/black) as a autoformatter tool
-and checker and a few linters.
+The project uses [black](https://github.com/psf/black) as an autoformatter
+and checker, along with a few linters.
 
 ## Tests
 
-To run tests you have to install [tox](https://tox.readthedocs.io/en/latest/).
+To run tests you need to install [tox](https://tox.readthedocs.io/en/latest/).
 
 Run tests:
 
 ```shell
 tox
 ```
 
-Run a specific test using python 3.11:
+Run a specific test using python 3.12:
 
 ```shell
 tox -e py311 -- -k test_add_message_handler

README.md

@@ -22,6 +22,13 @@ pip install python-telegram
 
 See [documentation](http://python-telegram.readthedocs.io/en/latest/#installation) for more details.
 
+### tdlib
+
+`python-telegram` comes with a precompiled `tdlib` library for Linux and MacOS. But it is highly recommended to [compile](https://tdlib.github.io/td/build.html) it yourself.
+The precompiled library may not work on some systems, it is dynamically linked and requires specific versions of additional libraries.
+
+```shell
+
 ### Docker
 
 This library has a [docker image](https://hub.docker.com/r/akhmetov/python-telegram/):
@@ -33,9 +40,9 @@ docker run -i -t --rm \
             python3 /app/examples/send_message.py $(API_ID) $(API_HASH) $(PHONE) $(CHAT_ID) $(TEXT)
 ```
 
-## How to use
+## How to use the library
 
-Have a look at the [tutorial](http://python-telegram.readthedocs.io/en/latest/tutorial.html) :)
+Check out the [tutorial](http://python-telegram.readthedocs.io/en/latest/tutorial.html) for more details.
 
 Basic example:
 
@@ -52,19 +59,20 @@ tg = Telegram(
 )
 tg.login()
 
-# if this is the first run, library needs to preload all chats
-# otherwise the message will not be sent
+# If this is the first run, the library needs to preload all chats.
+# Otherwise, the message will not be sent.
 result = tg.get_chats()
 result.wait()
 
 chat_id: int
 result = tg.send_message(chat_id, Spoiler('Hello world!'))
-# `tdlib` is asynchronous, so `python-telegram` always returns you an `AsyncResult` object.
+
+# `tdlib` is asynchronous, so `python-telegram` always returns an `AsyncResult` object.
 # You can receive a result with the `wait` method of this object.
 result.wait()
 print(result.update)
 
-tg.stop()  # you must call `stop` at the end of the script
+tg.stop()  # You must call `stop` at the end of the script.
 ```
 
 You can also use `call_method` to call any [tdlib method](https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_function.html):
@@ -73,11 +81,11 @@ You can also use `call_method` to call any [tdlib method](https://core.telegram.
 tg.call_method('getUser',  params={'user_id': user_id})
 ```
 
-More examples you can find in the [/examples/ directory](/examples/).
+More examples can be found in the [/examples/ directory](/examples/).
 
 ---
 
-More information in the [documentation](http://python-telegram.readthedocs.io).
+More information is available in the [documentation](http://python-telegram.readthedocs.io).
 
 ## Development
 

docs/source/index.rst

@@ -13,19 +13,19 @@ Welcome to python-telegram's documentation
    proxy
    changelog
 
-Client for the `tdlib <https://github.com/tdlib/td>`_ library (at very early stage :) ).
+Client for the `tdlib <https://github.com/tdlib/td>`_ library.
 
 Installation
 ------------
 
-At first you must install ``tdlib``.
+First you need to install ``tdlib``.
 
 How to build tdlib
 ~~~~~~~~~~~~~~~~~~
 
 `Official documentation <https://github.com/tdlib/td#building>`_
 
-Do not forget install it after:
+After building the library, you need to install it:
 
 .. code-block:: bash
 
@@ -35,26 +35,26 @@ Do not forget install it after:
 Library installation
 ~~~~~~~~~~~~~~~~~~~~
 
-This library works with Python 3.8+ only.
+This library requires Python 3.8 or higher.
 
 .. code-block:: bash
 
      python3 -m pip install python-telegram
 
-After you must `register <http://my.telegram.org/apps/>`_ a new Telegram application.
+Next, you need to `register <http://my.telegram.org/apps/>`_ a new Telegram application.
 
 Now you can start using the library: :ref:`tutorial`.
 
 .. note::
-    You can find more examples `here <https://github.com/alexander-akhmetov/python-telegram/tree/master/examples>`_.
+    More examples can be found `here <https://github.com/alexander-akhmetov/python-telegram/tree/master/examples>`_.
 
 .. note::
-    The ``tdlib`` binary for Linux provided by ``python-shortcuts`` is built on Ubuntu with libc since version ``0.10.0``. Before ``0.10.0``, Alpine Linux was used with ``musl``.
+    The ``tdlib`` binary for Linux provided by ``python-shortcuts`` has been built on Ubuntu with libc strating from version ``0.10.0``. Versions before ``0.10.0`` were built on Alpine Linux with ``musl``.
 
 Docker
 ------
 
-This library has a `docker image <https://hub.docker.com/r/akhmetov/python-telegram/>`_
+A Docker image for this library is available `here <https://hub.docker.com/r/akhmetov/python-telegram/>`_
 
 .. code-block:: bash
 

docs/source/proxy.rst

@@ -7,7 +7,7 @@ Proxy
 How to use a proxy with tdlib
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Define proxy parameters and pass them to ``Telegram``:
+To use a proxy with tdlib, define the proxy parameters and pass them to the ``Telegram`` class:
 
 .. code-block:: python
 

docs/source/tutorial.rst

@@ -13,9 +13,9 @@ Install the library:
 
      python3 -m pip install python-telegram
 
-Let's create a simple echo-bot, which sends "pong" when it receives "ping".
+Let's create a simple echo-bot that sends "pong" when it receives "ping".
 
-Initialize a new telegram client with your credentials:
+Initialize a new Telegram client with your credentials:
 
 .. code-block:: python
 
@@ -29,32 +29,31 @@ Initialize a new telegram client with your credentials:
     )
 
 .. note::
-    The library (actually ``tdlib``) stores messages database and received files in the ``/tmp/.tdlib_files/{phone_number}/``.
+    The library configures ``tdlib`` to store the messages database and received files in the ``/tmp/.tdlib_files/{phone_number}/``.
     You can change this behaviour with the ``files_directory`` parameter.
 
 .. note::
-    You can use bot tokens: just pass ``bot_token`` instead of ``phone``.
+    You can pass bot tokens by passing ``bot_token`` instead of ``phone``.
 
-After that, you have to login:
+Now you need to login to the Telegram. You can do it by calling the `login` method:
 
 .. code-block:: python
 
     tg.login()
 
-In this example we use a blocking version of the `login` function.  You can find an example for non-blocking usage here: :ref:`non_blocking_login`.
-Telegram will send you a code in an SMS or as a Telegram message. If you have enabled 2FA, you will be asked for your password too. After successful login you can start using the library:
+In this example, we use a blocking version of the ``login`` function. You can find an example for non-blocking usage here: :ref:`non_blocking_login`.
+Telegram will send you a code via SMS or as a Telegram message. If you have enabled 2FA, you will also be asked for your password. After successful login, you can start using the library:
 
 .. code-block:: python
 
-    # this function will be called
-    # for each received message
+    # This function will be called for each received message.
     def new_message_handler(update):
         print('New message!')
 
     tg.add_message_handler(new_message_handler)
-    tg.idle()  # blocking waiting for CTRL+C
+    tg.idle()  # Blocking, waiting for CTRL+C.
 
-This code adds a new message handler which prints a simple text every time it receives a new message.
+This code adds a new message handler that prints a simple text every time it receives a new message.
 ``tg.idle()`` is neccessary to block your script and wait for an exit shortcut (``CTRL+C``).
 
 If you run this code, you will see something like that:
@@ -69,7 +68,7 @@ Let's add more logic to the message handler:
 .. code-block:: python
 
     def new_message_handler(update):
-        # we want to process only text messages
+        # We want to process only text messages.
         message_content = update['message']['content'].get('text', {})
         message_text = message_content.get('text', '').lower()
         is_outgoing = update['message']['is_outgoing']
@@ -97,7 +96,7 @@ Full code of our new bot:
     tg.login()
 
     def new_message_handler(update):
-        # we want to process only text messages
+        # We want to process only text messages.
         message_content = update['message']['content'].get('text', {})
         message_text = message_content.get('text', '').lower()
         is_outgoing = update['message']['is_outgoing']