Don't repeat documentation, link to it instead

also fix some typos and improve some markdown formatting.

README.md

@@ -9,37 +9,14 @@ About
 [Smack] is an Open Source, cross-platform, easy to use Java XMPP
 client library.
 
-Communicate with XMPP servers to perform real-time collaboration,
-including instant messaging and group chat.
-
-Key Advantages :
-  - Extremely simple to use, yet powerful API. Sending a text message to a user can be accomplished in only a few lines of code:
-
-    ```java
-    AbstractXMPPConnection connection = new XMPPTCPConnection("jabber.org");
-    connection.connect();
-    connection.login("mtucker", "password");
-    Chat chat = ChatManager.getInstanceFor(connection)
-        .createChat("jsmith@jivesoftware.com", new MessageListener() {
-
-        public void processMessage(Chat chat, Message message) {
-            System.out.println("Received message: " + message);
-        }
-    });
-    chat.sendMessage("Howdy!");
-    ```
-
-  - Doesn't force you to code at the packet level, as other libraries do. Smack provides intelligent higher level constructs such as the Chat and Roster classes, which let you program more efficiently.
-  - Does not require that you're familiar with the XMPP XML format, or even that you're familiar with XML.
-  - Provides easy machine to machine communication. Smack lets you set any number of properties on each message, including properties that are Java objects.
-  - Open Source under the Apache License, which means you can incorporate Smack into your commercial or non-commercial applications.
-
 [Smack] is an Open Source [XMPP (Jabber)] client library for instant
 messaging and presence. A pure Java library, it can be embedded into
 your applications to create anything from a full XMPP client to simple
 XMPP integrations such as sending notification messages and
 presence-enabling devices.
 
+Confused? Have a look at the [Overview](documentation/overview.md).
+
 [Smack] - an [Ignite Realtime] community project.
 
 Bug Reporting
@@ -48,21 +25,21 @@ Bug Reporting
 Only a few usrs have acces for for filling bugs in the tracker. New
 users should:
 
-1. Create a forums account (only e-mail is a requirement, you can skip all the other fields).
+1. [Create a forums account](https://community.igniterealtime.org/login!input.jspa?registerOnly=true) (only e-mail is a requirement, you can skip all the other fields).
-2. Login to a forum account
+2. Login to the forum account
 3. Press New in your toolbar and choose Discussion
-4. Choose the [Smack Dev forum](http://community.igniterealtime.org/community/developers/smack) of Smack and add the tag 'bug_report' to your new post
+4. Choose the [Smack Developers Forum] of Smack and add the tag 'bug_report' to your new post
 
 Please search for your issues in the bug tracker before reporting.
 
 Contact
 -------
 
-The developeres hang around in #smack (freenode, IRC). Remeber that it
+The developeres hang around in `#smack` (freenode, IRC). Remember that it
 may take some time (~hours) to get a response.
  
 You can also reach us via the
-[Smack Developers Forum](http://community.igniterealtime.org/community/developers/smack).
+[Smack Users Forum] if you have questions or need support, or the [Smack Developers Forum] if you want to discuss Smack development.
 
 Resources
 ---------
@@ -87,3 +64,5 @@ of the biggest and most active Open Source communities.
 [Smack]: http://www.igniterealtime.org/projects/smack/index.jsp
 [Ignite Realtime]: http://www.igniterealtime.org
 [XMPP (Jabber)]: http://xmpp.org/
+[Smack Developers Forum]: http://community.igniterealtime.org/community/developers/smack
+[Smack Users Forum]: https://community.igniterealtime.org/community/support/smack_users

documentation/overview.md

@@ -1,4 +1,5 @@
 Smack Overview
+==============
 
 [Back](index.html)
 
@@ -6,21 +7,23 @@ Smack is a library for communicating with XMPP servers to perform real-time
 communications, including instant messaging and group chat.
 
 Smack Key Advantages
+--------------------
 
   * Extremely simple to use, yet powerful API. Sending a text message to a user can be accomplished in only a few lines of code: 
 
-
+    ```java
-    XMPPConnection connection = new XMPPTCPConnection("xmpp.org");
+    AbstractXMPPConnection connection = new XMPPTCPConnection("jabber.org");
     connection.connect();
     connection.login("mtucker", "password");
-    Chat chat = connection.getChatManager().createChat("jsmith@jivesoftware.com", new MessageListener() {
+    Chat chat = ChatManager.getInstanceFor(connection)
-    
+        .createChat("jsmith@jivesoftware.com", new MessageListener() {
+
         public void processMessage(Chat chat, Message message) {
             System.out.println("Received message: " + message);
         }
     });
     chat.sendMessage("Howdy!");
-
+    ```
 
 * Doesn't force you to code at the packet level, as other libraries do. Smack provides intelligent higher level constructs such as the `Chat` and `Roster` classes, which let you program more efficiently. 
   * Does not require that you're familiar with the XMPP XML format, or even that you're familiar with XML. 
@@ -28,12 +31,14 @@ Smack Key Advantages
   * Open Source under the Apache License, which means you can incorporate Smack into your commercial or non-commercial applications. 
 
 About XMPP
+----------
 
 XMPP (eXtensible Messaging and Presence Protocol) is an open protocol
 standardized by the IETF and supported and extended by the XMPP Standards
 Foundation (([http://www.xmpp.org](http://www.xmpp.org)).
 
 How To Use This Documentation
+-----------------------------
 
 This documentation assumes that you're already familiar with the main features
 of XMPP instant messaging. It's also highly recommended that you open the