Readme update (#441)

* add dokkaRuntime config to the readme, add FAQ link

* change output formats description

1 files changed, 27 insertions, 5 deletions

diff --git a/README.md b/README.md
index 92ea9e2a..96a5b570 100644
--- a/README.md
+++ b/README.md
@@ -157,6 +157,28 @@ task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) {
 
 Please see the [Dokka Gradle example project](https://github.com/JetBrains/kotlin-examples/tree/master/gradle/dokka-gradle-example) for an example.
 
+#### Dokka Runtime
+If you are using Gradle plugin and you want to change the version of Dokka, you can do it by setting `dokkaRuntime`:
+
+```groovy
+buildscript {
+    ...
+}
+
+apply plugin: 'org.jetbrains.dokka'
+
+repositories {
+    jcenter()
+}
+
+dependencies {
+    dokkaRuntime "org.jetbrains.dokka:dokka-fatjar:0.9.18"
+}
+```
+
+#### FAQ
+Please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq).
+
 #### Android
 
 If you are using Android there is a separate Gradle plugin. Just make sure you apply the plugin after
@@ -396,11 +418,11 @@ Dokka supports the following command line arguments:
 
 ### Output formats<a name="output_formats"></a>
 
-  * `html` - minimalistic html format used by default
-  * `javadoc` - Dokka mimic to javadoc
-  * `html-as-java` - as `html` but using java syntax
-  * `markdown` - Markdown structured as `html`
-    * `gfm` - GitHub flavored markdown  
+  * `html` - minimalistic html format used by default, Java classes are translated to Kotlin
+  * `javadoc` - looks like normal Javadoc, Kotlin classes are translated to Java
+  * `html-as-java` - looks like `html`, but Kotlin classes are translated to Java
+  * `markdown` - markdown structured as `html`, Java classes are translated to Kotlin
+    * `gfm` - GitHub flavored markdown
     * `jekyll` - Jekyll compatible markdown 
   * `kotlin-website*` - internal format used for documentation on [kotlinlang.org](https://kotlinlang.org)