Add narrative documentation about creating bots

Author: Pietro Albini

docs/bot-creation.rst

@@ -0,0 +1,60 @@
+.. Copyright (c) 2016 Pietro Albini <[email protected]>
+   Released under the MIT license
+
+.. _bot-creation:
+
+=========================
+Create a new Telegram bot
+=========================
+
+Before you start writing any code, you should create your bot on Telegram. This
+reserves your bot an username, and gives you the API key you need to control
+your bot. This chapter explains you how to do so.
+
+.. _bot-creation-naming:
+
+Choose a good username for your bot
+===================================
+
+The username of your bot is really important: users will use it to tell their
+friends about your bot, and it will appear on telegram.me links. Also, you're
+not allowed to change username without recreating your bot, and so without
+losing users.
+
+Bot usernames must adhere to the following rules:
+
+* The username must be long at least five characters
+* The username can only contain letters, digits and underscores
+* The username must end with ``bot``
+
+For example, all the following usernames are valid: ``my_awesome_bot``,
+``SpamBot``, ``test123bot``.
+
+.. _bot-creation-botfather:
+
+Create the bot with @botfather
+==============================
+
+Currently, you can only create a new bot... with another bot. With your
+Telegram client open, contact `@botfather`_, start it and execute the
+``/newbot`` command. It will ask you some questions about your bot.
+
+Then it will give you an unique API key, which you can use to communicate with
+your bot. **Be sure to keep this key secret!** Everyone with your API key can
+take full control of your bot, and that's not a fun thing.
+
+.. _bot-creation-customization:
+
+Customize your bot
+==================
+
+Other than allowing you to create it, `@botfather`_ also permits you to
+customize your bot. For example, you can use it to change your bot's avatar,
+its name, or its description. In order to see what you can do, just use the
+``/help`` command on @botfather. Then execute the command for the thing you
+want to customize.
+
+If you want to use your bot just to manage a channel, you probably don't need
+to do this.
+
+.. _@botfather: https://telegram.me/botfather

docs/channels.rst

@@ -18,17 +18,13 @@ With botogram you can easily do that, without even the need to run the bot.
 Preparation
 ===========
 
-In order to start working with channels, you need to get a bot's API key. If
-you already have a bot you can skip this step. First of all you need to contact
-the `@botfather`_ Telegram account, and then send to it the ``/newbot``
-command. After you provide all the information he needs, you will get an API
-key, which looks like this fake one::
+Before you can start working with channels, you need to create a bot which will
+be able to send messages to your channel. If you haven't done that already,
+check the :ref:`bot creation <bot-creation>` chapter of this documentation.
 
-   123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghi
-
-The final step is to add your bot as an administrator of the channel. Open your
-favourite Telegram client, and go to the administrators' section of your
-channel. From it you should add your bot, and then you're ready.
+After that you need to allow your bot to send messages to your channel. Open
+your favorite Telegram client, and go to the administrators' section of your
+channel. From there you should add your bot, and then you're ready.
 
 .. _channels-standalone:
 

docs/index.rst

@@ -53,6 +53,7 @@ Narrative documentation
 .. toctree::
    :maxdepth: 2
 
+   bot-creation
    shared-memory
    tasks
    custom-components

docs/quickstart/api-key.rst

@@ -20,8 +20,10 @@ it needs to know, it will give you an API key, like this fake one::
 
    123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghi
 
-Write it down somewhere. You can further customize the bot from that chat,
-check `the @botfather documentation`_ if you want to know more.
+Write it down somewhere, but **be sure to keep it secret!** Everyone with your
+API key can take full control of your bot, and that's not a fun thing.
+
+If you want to learn more about creating and customizing bots, check the
+:ref:`bot creation <bot-creation>` chapter of this documentation.
 
 .. _@botfather: https://telegram.me/botfather
-.. _the @botfather documentation: https://core.telegram.org/bots/#botfather