Add an initial user manual for converse.js

docs/source/index.rst

@@ -13,6 +13,8 @@ Preface
 This is the official documentation for Converse.js. If you'd like to
 contribute, please read the :doc:`documentation` page.
 
+You might instead be looking for the `User Manual <manual.html>`_.
+
 Introduction
 ============
 
@@ -46,3 +48,4 @@ Table of Contents
    translations
    documentation
    builds
+

docs/source/manual.rst

+===========================
+The Converse.js User Manual
+===========================
+
+.. |br| raw:: html
+
+   <br />
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+.. figure:: images/homepage.jpg
+   :align: right
+   :alt: The converse.js website
+
+   The converse.js website
+
+**Welcome to the converse.js user manual**. This manual is very much still a work
+in progress and is far from complete. Please bear in mind that it's the work of volunteers.
+
+If you have requests or suggestions on how the manual can be improved or
+expanded, then please `contact me <https://opkode.com/contact.html>`_
+or create a new ticket on `Github <https://github.com/jcbrand/converse.js/issues>`_.
+
+Although converse.js can be integrated into any website, for this user manual
+we'll refer to the canonical version at https://conversejs.org.
+
+This documentation also integrates the converse.js chat client, so you can try
+out some of the steps right on this page! Just click the **Toggle chat** button
+at the bottom right of the page to open the so-called *control box* of the
+converse.js chat client.
+
+Registering a new chat account
+==============================
+
+.. figure:: images/register-panel.jpg
+   :align: left
+   :alt: The registration panel of the converse.js control box.
+
+   The registration panel of converse.js
+
+With converse.js you can register a new XMPP account on any publically available XMPP provider.
+To do so, click the **Register** tab on the chat client.
+
+You will then see the *registration panel* as shown in the picture below.
+
+Choosing your provider
+----------------------
+
+Converse.js uses a chat protocol called XMPP (also known as Jabber) which allows "federation".
+This means that it's similar to email, in the sense that people signed in at
+different XMPP chat providers can still chat with one another.
+
+For example, if you have a Yahoo! email account, you can send and receive emails from
+a friend with a Google email account. In the same way, if you have a chat
+account from **Conversejs.org**, you can send and receive chat messages with a
+friend who has an account at `Jappix.com <https://jappix.com>`_.
+
+There are many free providers online which allow you to register a new account.
+You can see a list of some of them at `xmpp.net <https://xmpp.net/directory.php>`_.
+The `xmpp.net <https://xmpp.net/directory.php>`_ website provides a security grading
+for the XMPP servers of the providers, which is very useful. They are however sometimes
+slow to add new servers to the list.
+A larger list of XMPP providers is also available at `list.jabber.net <https://list.jabber.at/>`_.
+
+You can find the domain name for a server under the *Domain* column at
+`xmpp.net <https://xmpp.net/directory.php>`_. or the *Server* column at
+`list.jabber.net <https://list.jabber.at/>`_.
+
+Once you know which XMPP provider you'd like to use, you can type its domain
+name and click the **Fetch registration form** button.
+
+|br|
+
+.. figure:: images/register-form.jpg
+   :align: left
+   :alt: The registration form for an XMPP account at conversejs.org
+
+   The registration form
+
+
+Filling out the registration form
+---------------------------------
+
+After you've clicked **Fetch registration form**, the chat client will contact
+the chat provider, ask for its registration form and then present it to you.
+
+Different chat providers have different registration forms, but they're all
+relatively similar.
+
+Check the security score
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+At the top of the form you'll see a colored bar containing the text **xmpp.net score**.
+This shows the security score for this server as determined by `xmpp.net <https://xmpp.net>`_
+where you can test out a server for yourself. You should generally avoid providers with
+a poor security score (colored in red).
+
+Choosing a username
+~~~~~~~~~~~~~~~~~~~
+
+As you can see in the registration form, the **username** consists of two
+parts separated with an **@** sign, similar to an email address.
+
+The first part is your unique *handle* which you need to choose. The second part
+is the domain name of the chat provider, the one which you chose in the previous step
+when you fetched the registration form.
+
+When you want to give someone your XMPP chat username, or when you want to add
+someone else as a contact, you need to specify it in full, like you would an email address.
+
+Once you've chosen your user name and password, click **Register**. If
+Successful, you'll be automatically logged in to your new account.
+
+|br|
+
+.. figure:: images/add-contact.png
+   :align: left
+   :alt: Adding a contact in converse.js
+
+   The form for adding a new contact
+
+
+Adding a contact
+================
+
+In order to start chatting with someone, you first need to add them as a contact.
+
+To do this, click the **Add a contact** link in the **Contacts** tab. This will
+slide open a dropdown in which you can type the username of the person you'd
+like to add.
+
+Remember, an XMPP username (also called a JID or Jabber ID) is similar to an
+email address, in that you have both the user's *handle* and the *domain name*
+of the provider, separated with an **@** sign.
+
+Once you've typed the username and clicked submit, your request will be sent to
+this person. If they are online, they will immediately be notified of your
+request, otherwise they'll see it next time they come online.
+
+Technically, when you add someone as a contact, you're doing two things. Firstly,
+you are adding the contact to your *roster* (think of it as an address book) and secondly
+you are asking to be notified whenever that person comes online.
+
+.. figure:: images/pending-contact.jpg
+   :align: left
+   :alt: A pending contact
+
+   A pending contact
+
+A pending contact
+-----------------
+
+The person you are adding as a contact has the option to either accept or decline your request.
+Until that decision has been made, they will appear in your roster as a
+so-called *pending* contact. In other words, their final status is pending on whether
+they accept or decline your request.
+
+.. figure:: images/ungrouped-contact.png
+   :align: right
+   :alt: A normal, ungrouped contact
+
+   A normal contact
+
+A normal contact
+----------------
+
+If the person accepts your contact request, they will get a *chat status
+indicator* in your roster and will also become clickable. Clicking on the name
+of the user will open a chat box in which you can then start chatting with that
+user.
+
+.. figure:: images/remove-contact.png
+   :align: left
+   :alt: Removing a contact
+
+   Removing a contact
+
+Removing a contact
+==================
+
+To remove a contact, hover your mouse over their name and then click on the
+trash icon. You will be prompted to confirm, and if you do, the contact will no
+longer be visible in your roster.
+

index.html

@@ -58,6 +58,9 @@
                     <li class="page-scroll">
                         <a href="#contact">Contact</a>
                     </li>
+                    <li>
+                        <a href="/docs/html/manual.html">User Manual</a>
+                    </li>
                     <li>
                         <a href="/docs/html/index.html">Documentation</a>
                     </li>