Re-writing README, stage 1.

README.md

@@ -1,30 +1,23 @@
 # Telebot
->Telebot is a Telegram bot framework in Go.
+>"I never knew creating bots in Telegram was so _easy_!"
 
-[![GoDoc](https://godoc.org/github.com/tucnak/telebot?status.svg)](https://godoc.org/github.com/tucnak/telebot)
-[![Travis](https://travis-ci.org/tucnak/telebot.svg?branch=master)](https://travis-ci.org/tucnak/telebot)
-
-Bots are special Telegram accounts designed to handle messages automatically.
-Users can interact with bots by sending them command messages in private or
-via group chats / channels. These accounts serve as an interface to your code.
-
-Telebot offers a pretty convenient interface to Bots API and uses default HTTP
-client. Ideally, you wouldn't need to worry about actual networking at all.
+[![GoDoc](https://godoc.org/gopkg.in/tucnak/telebot.v2?status.svg)](https://godoc.org/gopkg.in/tucnak/telebot.v2)
+[![Travis](https://travis-ci.org/tucnak/telebot.svg?branch=v2)](https://travis-ci.org/tucnak/telebot)
 
 ```bash
 go get gopkg.in/tucnak/telebot.v2
 ```
 
-(after setting up your `GOPATH` properly).
-
-We highly recommend you to keep your bot access token outside the code base,
-preferably in an environmental variable:
-
-```bash
-export BOT_TOKEN=<your token here>
-```
+Telebot is a bot framework for Telegram Bots API. This package provides a super convenient API
+for command routing, message and inline query requests, as well as callbacks. Actually, I went a
+couple steps further and instead of making a 1:1 API wrapper I focused on the beauty of API and
+bot performance. All the methods of telebot API are _extremely_ easy to remember and later, get
+used to. Telebot is agnostic to the source of updates as long as it implements the Poller interface.
+Poller means you can plug your telebot into virtually any bot infrastructure, if you have any. Also,
+consider Telebot a highload-ready solution. I'll soon benchmark the most popular actions and if
+necessary, optimize against them without sacrificing API quality.
 
-Take a look at a minimal functional bot setup:
+Take a look at the minimal telebot setup:
 ```go
 import (
     "time"
@@ -49,40 +42,38 @@ func main() {
 }
 ```
 
-## Inline mode
-As of January 4, 2016, Telegram added inline mode support for bots. Here's
-a nice way to handle both incoming messages and inline queries:
+Simple, innit? Telebot's routing system takes care of deliviering updates
+to their "endpoints", so in order to get handle any meaningful event,
+all you have to do is just plug your handler to one of them endpoints
+and you're ready to go! You might want to switch-case handle more specific
+scenarios later.
 
 ```go
-import (
-    "time"
-    tb "gopkg.in/tucnak/telebot.v2"
-)
-
-func main() {
-    b, err := tb.NewBot(tb.Settings{
-        Token: "TOKEN_HERE",
-        Poller: &tb.LongPoller{10 * time.Second},
-    })
-
-    if err != nil {
-        return
-    }
+b, _ := tb.NewBot(settings)
 
-    b.Handle(tb.OnMessage, func(m *tb.Message) {
-        b.Send(m.From, "hello world")
-    }
+b.Handle("/help", func (m *Message) {
+    // help command handler
+}
 
-    b.Handle(tb.OnQuery, func(q *tb.Query) {
-        b.Answer(q, ...)
-    }
+b.Handle(tb.OnChannelPost, func (m *Message) {
+    // channel post messages only
+})
 
-    b.Start()
+b.Handle(tb.Callback, func (c *Callback) {
+    // incoming bot callbacks
+})
 }
 ```
 
+Moreover, this API is completely extensible, so new handy endpoints might
+appear in the following minor versions of this package.
+
+## Inline mode
+Docs TBA.
+
 ## Files
-Telebot allows to both upload and download certain files.
+Telebot allows to both upload (from disk / by URL) and download (from Telegram)
+and files in bot's scope. Telegram allows files up to 20 MB in size.
 
 ```go
 a := &tb.Audio{File: tb.FromDisk("file.ogg")}
@@ -90,27 +81,20 @@ a := &tb.Audio{File: tb.FromDisk("file.ogg")}
 fmt.Println(a.OnDisk()) // true
 fmt.Println(a.InCloud()) // false
 
-// Next time you'll be sending this very *Audio, Telebot won't
-// re-upload the same file but rather use the copy from the
-// server.
+// Will upload the file from disk and send it to recipient
 bot.Send(recipient, a)
 
+// Next time you'll be sending this very *Audio, Telebot won't
+// re-upload the same file but rather utilize its Telegram FileID
+bot.Send(otherRecipient, a)
+
 fmt.Println(a.OnDisk()) // true
 fmt.Println(a.InCloud()) // true
 fmt.Println(a.FileID) // <telegram file id: ABC-DEF1234ghIkl-zyx57W2v1u123ew11>
 ```
 
 You might want to save certain files in order to avoid re-upploading. Feel free
-to marshal them into whatever format, Files only contain public fields, so no
-data will be lost.
+to marshal them into whatever format, `File` only contain public fields, so no
+data will ever be lost.
 
-## Reply markup
-```go
-// Send a selective force reply message.
-bot.Send(user, "pong", &tb.ReplyMarkup{
-    ForceReply: true,
-    Selective: true,
-
-    ReplyKeyboard: keys,
-})
-```
+TBA.