Initial work on improving docs.

docs/getting-started/README.md

@@ -0,0 +1,112 @@
+# Getting Started
+
+This library is designed as a simple wrapper around the Telegram Bot API.
+It's encouraged to read [Telegram's docs][telegram-docs] first to get an
+understanding of what Bots are capable of doing. They also provide some good
+approaches to solve common problems.
+
+[telegram-docs]: https://core.telegram.org/bots
+
+## Installing
+
+```bash
+go get -u github.com/go-telegram-bot-api/telegram-bot-api@develop
+```
+
+It's currently suggested to use the develop branch. While there may be breaking
+changes, it has a number of features not yet available on master.
+
+## A Simple Bot
+
+To walk through the basics, let's create a simple echo bot that replies to your
+messages repeating what you said. Make sure you get an API token from
+[@Botfather][botfather] before continuing.
+
+Let's start by constructing a new [BotAPI][bot-api-docs].
+
+[botfather]: https://t.me/Botfather
+[bot-api-docs]: https://pkg.go.dev/github.com/go-telegram-bot-api/telegram-bot-api/v5?tab=doc#BotAPI
+
+```go
+package main
+
+import (
+    "os"
+
+    "github.com/go-telegram-bot-api/telegram-bot-api/v5"
+)
+
+func main() {
+    bot, err := tgbotapi.NewBotAPI(os.Getenv("TELEGRAM_APITOKEN"))
+    if err != nil {
+        panic(err)
+    }
+
+    bot.Debug = true
+}
+```
+
+Instead of typing the API token directly into the file, we're using
+environment variables. This makes it easy to configure our Bot to use the right
+account and prevents us from leaking our real token into the world. Anyone with
+your token can send and receive messages from your Bot!
+
+We've also set `bot.Debug = true` in order to get more information about the
+requests being sent to Telegram. If you run the example above, you'll see
+information about a request to the [`getMe`][get-me] endpoint. The library
+automatically calls this to ensure your token is working as expected. It also
+fills in the `Self` field in your `BotAPI` struct with information about the
+Bot.
+
+Now that we've connected to Telegram, let's start getting updates and doing
+things. We can add this code in right after the line enabling debug mode.
+
+[get-me]: https://core.telegram.org/bots/api#getme
+
+```go
+    // Create a new UpdateConfig struct with an offset of 0. Offsets are used
+    // to make sure Telegram knows we've handled previous values and we don't
+    // need them repeated.
+    updateConfig := tgbotapi.NewUpdate(0)
+
+    // Tell Telegram we should wait up to 30 seconds on each request for an
+    // update. This way we can get information just as quickly as making many
+    // frequent requests without having to send nearly as many.
+    updateConfig.Timeout = 30
+
+    // Start polling Telegram for updates.
+    updates := bot.GetUpdatesChan(updateConfig)
+
+    // Let's go through each update that we're getting from Telegram.
+    for update := range updates {
+        // Telegram can send many types of updates depending on what your Bot
+        // is up to. We only want to look at messages for now, so we can
+        // discard any other updates.
+        if update.Message == nil {
+            continue
+        }
+
+        // Now that we know we've gotten a new message, we can construct a
+        // reply! We'll take the Chat ID and Text from the incoming message
+        // and use it to create a new message.
+        msg := tgbotapi.NewMessage(update.Message.Chat.ID, update.Message.Text)
+        // We'll also say that this message is a reply to the previous message.
+        // For any other specifications than Chat ID or Text, you'll need to
+        // set fields on the `MessageConfig`.
+        msg.ReplyToMessageID = update.Message.MessageID
+
+        // Okay, we're sending our message off! We don't care about the message
+        // we just sent, so we'll discard it.
+        if _, err := bot.Send(msg); err != nil {
+            // Note that panics are a bad way to handle errors. Telegram can
+            // have service outages or network errors, you should retry sending
+            // messages or more gracefully handle failures.
+            panic(err)
+        }
+    }
+```
+
+Congradulations! You've made your very own bot!
+
+Now that you've got some of the basics down, we can start talking about how the
+library is structured and more advanced features.

docs/getting-started/files.md

@@ -0,0 +1,66 @@
+# Files
+
+Telegram supports specifying files in many different formats. In order to
+accommodate them all, there are multiple structs and type aliases required.
+
+| Type | Description |
+| ---- | ----------- |
+| `string` | Used as a local path to a file |
+| `FileID` | Existing file ID on Telegram's servers |
+| `FileURL` | URL to file, must be served with expected MIME type |
+| `FileReader` | Use an `io.Reader` to provide a file. Lazily read to save memory. |
+| `FileBytes` | `[]byte` containing file data. Prefer to use `FileReader` to save memory. |
+
+## `string`
+
+A path to a local file.
+
+```go
+file := "tests/image.jpg"
+```
+
+## `FileID`
+
+An ID previously uploaded to Telegram. IDs may only be reused by the same bot
+that received them. Additionally, thumbnail IDs cannot be reused.
+
+```go
+file := tgbotapi.FileID("AgACAgIAAxkDAALesF8dCjAAAa_…")
+```
+
+## `FileURL`
+
+A URL to an existing resource. It must be served with a correct MIME type to
+work as expected.
+
+```go
+file := tgbotapi.FileURL("https://i.imgur.com/unQLJIb.jpg")
+```
+
+## `FileReader`
+
+Use an `io.Reader` to provide file contents as needed. Requires a filename for
+the virtual file.
+
+```go
+var reader io.Reader
+
+file := tgbotapi.FileReader{
+    Name: "image.jpg",
+    Reader: reader,
+}
+```
+
+## `FileBytes`
+
+Use a `[]byte` to provide file contents. Generally try to avoid this as it
+results in high memory usage. Also requires a filename for the virtual file.
+
+```go
+var data []byte
+
+file := tgbotapi.FileBytes{
+    Name: "image.jpg",
+    Bytes: data,
+}
+```

docs/getting-started/library-structure.md

@@ -0,0 +1,37 @@
+# Library Structure
+
+This library is generally broken into three components you need to understand.
+
+## Configs
+
+Configs are collections of fields related to a single request. For example, if
+one wanted to use the `sendMessage` endpoint, you could use the `MessageConfig`
+struct to configure the request. There is a one-to-one relationship between
+Telegram endpoints and configs. They generally have the naming pattern of
+removing the `send` prefix and they all end with the `Config` suffix. They
+generally implement the `Chattable` interface. If they can send files, they
+implement the `Fileable` interface.
+
+## Helpers
+
+Helpers are easier ways of constructing common Configs. Instead of having to
+create a `MessageConfig` struct and remember to set the `ChatID` and `Text`,
+you can use the `NewMessage` helper method. It takes the two required parameters
+for the request to succeed. You can then set fields on the resulting
+`MessageConfig` after it's creation. They are generally named the same as
+method names except with `send` replaced with `New`.
+
+## Methods
+
+Methods are used to send Configs after they are constructed. Generally,
+`Request` is the lowest level method you'll have to call. It accepts a
+`Chattable` parameter and knows how to upload files if needed. It returns an
+`APIResponse`, the most general return type from the Bot API. This method is
+called for any endpoint that doesn't have a more specific return type. For
+example, `setWebhook` only returns `true` or an error. Other methods may have
+more specific return types. The `getFile` endpoint returns a `File`. Almost
+every other method returns a `Message`, which you can use `Send` to obtain.
+
+There's lower level methods such as `MakeRequest` which require an endpoint and
+parameters instead of accepting configs. These are primarily used internally.
+If you find yourself having to use them, please open an issue.