Update documentation and README.md

README.md

@@ -6,14 +6,10 @@ Smack
 About
 -----
 
-[Smack] is an Open Source, cross-platform, easy to use Java XMPP
-client library.
-
-[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.
+[Smack] is an open source, cross-platform, easy to use, Java XMPP client library.
+
+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.
+Smack and XMPP allows you to easily exchange data, in various ways e.g. fire-and-forget, publish-subscribe, between human and non-human endpoints.
 
 Confused? Have a look at the [Overview](documentation/overview.md).
 

documentation/developer/stanzas.md

@@ -4,12 +4,13 @@ General Rules
 All classes which subclass `TopLevelStreamElement` and `ExtensionElement` must either
 
 1. be immutable (and ideally provide a Builder)
-2. implemented `TypedCloneable`
+2. implement `TypedCloneable`
 
 and must be `Serializable`.
 The reason that it must be either 1. or 2. is that it makes no sense to clone an inmutable instance.
+The preferred option is 1.
 
-Note that there is legacy code in Smack which does not follow these rules. Patches welcome.
+Note that there is legacy code in Smack which does not follow these rules. Patches are welcome.
 
 ExtensionElement
 ================

documentation/gettingstarted.md

@@ -14,6 +14,7 @@ library ships as several JAR files to provide more flexibility over which
 features applications require:
 
   * `smack-core.jar` -- provides core XMPP functionality. All XMPP features that are part of the XMPP RFCs are included.
+  * `smack-im.jar` -- provides functinoality defined in RFC 6121 (XMPP-IM), like the Roster.
   * `smack-tcp.jar` -- support for XMPP over TCP. Includes XMPPTCPConnection class, which you usually want to use
   * `smack-extensions.jar` -- support for many of the extensions (XEPs) defined by the XMPP Standards Foundation, including multi-user chat, file transfer, user search, etc. The extensions are documented in the [extensions manual](extensions/index.md).
   * `smack-experimental.jar` -- support for experimental extensions (XEPs) defined by the XMPP Standards Foundation. The API and functionality of those extensions should be considered as unstable.

documentation/overview.md

@@ -17,7 +17,7 @@ Smack Key Advantages
 
     Chat chat = ChatManager.getInstanceFor(connection)
         .createChat("[email protected]", new MessageListener() {
-
+		@Override
         public void processMessage(Chat chat, Message message) {
             System.out.println("Received message: " + message);
         }
@@ -35,7 +35,7 @@ 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)).
+Foundation (XSF, [http://www.xmpp.org](http://www.xmpp.org)).
 
 How To Use This Documentation
 -----------------------------