Flesh out README

README.md

@@ -4,12 +4,132 @@
 [![Build Status](https://github.com/Vonage/vonage-kotlin-sdk/actions/workflows/build.yml/badge.svg)](https://github.com/Vonage/vonage-kotlin-sdk/actions/workflows/build.yml)
 [![codecov](https://codecov.io/gh/vonage/vonage-kotlin-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/vonage/vonage-kotlin-sdk)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
-[![Snyk](https://snyk.io/test/github/vonage/vonage-java-sdk/badge.svg)](https://snyk.io/test/github/vonage/vonage-java-sdk)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE.txt)
 
-This SDK provides syntactic sugar for the [Vonage Java Server SDK](https://github.com/Vonage/vonage-java-sdk)
-to improve the user experience in Kotlin. It is therefore subject to the same requirements and capabilities.
 
+This Kotlin SDK allows you to use [Vonage APIs](https://developer.vonage.com/api) in any JVM-based application.
 You'll need to have [created a Vonage account](https://dashboard.nexmo.com/sign-up?utm_source=DEV_REL&utm_medium=github&utm_campaign=java-client-library).
 
+* [Supported APIs](#supported-apis)
+* [Other SDKs](#other-sdks)
+* [Installation](#installation)
+* [Usage](#usage)
+* [Configuration](#configuration)
+* [FAQ](#frequently-asked-questions)
+* [Contribute!](#contribute)
 
+## Supported APIs
+- [Messages](https://developer.vonage.com/en/messages/overview)
+- [Verify](https://developer.vonage.com/en/verify/overview)
+
+## Other SDKs
+
+We also provide server SDKs in other languages:
+- [Java](https://github.com/Vonage/vonage-java-sdk)
+- [.NET](https://github.com/Vonage/vonage-dotnet-sdk)
+- [PHP](https://github.com/Vonage/vonage-php-sdk)
+- [Python](https://github.com/Vonage/vonage-python-sdk)
+- [Ruby](https://github.com/Vonage/vonage-ruby-sdk)
+- [NodeJS](https://github.com/Vonage/vonage-node-sdk)
+
+We also offer [client-side SDKs](https://developer.vonage.com/en/vonage-client-sdk/overview) for iOS, Android and JavaScript.
+See all of our SDKs and integrations on the [Vonage Developer portal](https://developer.vonage.com/en/tools).
+
+## Installation
+
+Releases are published to [Maven Central](https://central.sonatype.com/artifact/com.vonage/kotlin-server-sdk).
+Instructions for your build system can be found in the snippets section.
+They're also available from [here](https://mvnrepository.com/artifact/com.vonage/kotlin-server-sdk/latest).
+Release notes can be found in the [changelog](CHANGELOG.md).
+
+### Build It Yourself
+
+Alternatively you can clone the repo and build the JAR file yourself:
+
+```bash
+git clone git@github.com:vonage/vonage-kotlin-sdk.git
+mvn install
+```
+
+### Download everything in a ZIP file
+
+**Note**: We *strongly recommend* that you use a tool that supports dependency management,
+such as [Maven](https://maven.apache.org/), [Gradle](https://gradle.org/) or [Ivy](http://ant.apache.org/ivy/).
+
+We provide a [ZIP file for each release](https://github.com/Vonage/vonage-kotlin-sdk/releases/),
+containing the Java Server SDK JAR, along with all the dependencies. Download the file, unzip it, and add the JAR files
+to your project's classpath.
+
+## Usage
+
+* For help understanding our APIs, check out our awesome [developer portal](https://developer.vonage.com/).
+* Check the [Javadoc](https://www.javadoc.io/doc/com.vonage/kotlin-server-sdk/latest/index.html) for full reference documentation.
+* There are also **many useful code samples** in our [Vonage/vonage-kotlin-code-snippets](https://github.com/Vonage/vonage-kotlin-code-snippets) repository.
+
+## Configuration
+
+## Typical Instantiation
+For default configuration, you just need to specify your Vonage account credentials using API key and secret, private
+key and application ID or both. For maximum compatibility with all APIs, it is recommended that you specify both
+authentication methods, like so:
+
+```kotlin
+import com.vonage.client.kt.Vonage
+
+val vonage = Vonage {
+    apiKey(API_KEY); apiSecret(API_SECRET)
+    applicationId(APPLICATION_ID)
+    privateKeyPath(PRIVATE_KEY_PATH)
+}
+```
+
+You can also use environment variables for convenience, by setting the following:
+- `VONAGE_API_KEY`
+- `VONAGE_API_SECRET`
+- `VONAGE_APPLICATION_ID`
+- `VONAGE_PRIVATE_KEY_PATH`
+
+and then instantiate the client with:
+
+```kotlin
+val vonage = Vonage { authFromEnv() }
+```
+
+### Customization
+You can configure the base URI (for example, to do integration tests) and HTTP request timeout with `httpConfig`
+during instantiation, like so:
+
+```kotlin
+val vonageClient = Vonage {
+    authFromEnv()
+    httpConfig {
+        baseUri("http://localhost:8976")
+        timeoutMillis(15000)
+    }
+}
+```
+
+## Frequently Asked Questions
+
+**Q: Why use this SDK instead of the [Vonage Java Server SDK](https://github.com/Vonage/vonage-java-sdk)?**
+
+**A:** This Kotlin SDK is actually based on the to improve the user experience in Kotlin. It adds
+syntactic sugar, so you can avoid the cumbersome builder pattern in favour of a more idiomatic DSL-like
+syntax. Furthermore, you are more partially shielded from "platform types" (the `!`) so you have a better
+idea of what is and isn't nullable when creating requests.
+
+**Q: What is your policy on thread safety?**
+
+**A:** As with the Java Server SDK, only one thread should use the client at a time.
+If you would like to use the SDK in a multithreaded environment, create a separate instance of
+`Vonage` for each thread, or use a ThreadLocal instance.
+
+## Contribute!
+
+_We :heart: contributions to this library!_
+
+It is a good idea to [talk to us](https://developer.vonage.com/community/slack)
+first if you plan to add any new functionality.
+Otherwise, [bug reports](https://github.com/Vonage/vonage-kotlin-sdk/issues),
+[bug fixes](https://github.com/Vonage/vonage-kotlin-sdk/pulls) and feedback on the
+library are always appreciated.