Revise README documentation for examples and plugins (#2736)

1 files changed, 82 insertions, 34 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ca58ff4d..a19a9529 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,41 +1,89 @@
-## Building Dokka
-
-Dokka is built with Gradle. To build it, use `./gradlew build`.
-Alternatively, open the project directory in IntelliJ IDEA and use the IDE to build and run dokka.
-
-Here's how to import and configure Dokka in IntelliJ IDEA:
- * Select "Open" from the IDEA welcome screen, or File > Open if a project is
-  already open
-* Select the directory with your clone of Dokka
-  * Note: IDEA may have an error after the project is initally opened; it is OK
-    to ignore this as the next step will address this error
-* After IDEA opens the project, select File > New > Module from existing sources
-  and select the `build.gradle` file from the root directory of your Dokka clone
-* Use the default options and select "OK"
-* After Dokka is loaded into IDEA, open the Gradle tool window (View > Tool
-  Windows > Gradle) and click on the top left "Refresh all Gradle projects"
-  button
-* Verify the following project settings.  In File > Settings > Build, Execution,
-  Deployment > Build Tools > Gradle > Runner:
-  * Ensure "Delegate IDE build/run actions to gradle" is checked
-  * "Gradle Test Runner" should be selected in the "Run tests using" drop-down
-    menu
-* Note: After closing and re-opening the project, IDEA may give an error
-  message: "Error Loading Project: Cannot load 3 modules".  Open up the details
-  of the error, and click "Remove Selected", as these module `.iml` files are
-  safe to remove.
-
-## Using/testing locally built Dokka
-  
-If you want to use/test your locally built Dokka in a project, do the following:
+# Contributing Guidelines
+
+There are three main ways you can contribute to Dokka's development:
+
+* Submitting issues.
+* Submitting fixes/changes/improvements via pull requests.
+* Developing community plugins.
+
+## Submitting issues
+
+Bug reports, feature requests and questions are welcome. Submit issues [here](https://github.com/Kotlin/dokka/issues).
+
+* Search for existing issues to avoid reporting duplicates.
+* When submitting a bug report:
+   * Test it against the most recently released version. It might have been fixed already.
+   * Include code that reproduces the problem. Provide a complete reproducer, yet minimize it as much as 
+     possible. A separate project that can be cloned is ideal.
+   * If the bug is in behavior, explain what behavior you expected and what the actual result is.
+* When submitting a feature request:
+   * Explain why you need the feature.
+   * Explaining the problem you face is more important than suggesting a solution.
+     Report your problem even if you have no proposed solution.
+
+## Submitting PRs
+
+Dokka has extensive [Developer Guides](https://kotlin.github.io/dokka/1.7.20/developer_guide/introduction/) documentation
+which goes over the development [Workflow](https://kotlin.github.io/dokka/1.7.20/developer_guide/workflow/) and 
+[Dokka's architecture](https://kotlin.github.io/dokka/1.7.20/developer_guide/architecture/architecture_overview/),
+which can help you understand how to achieve what you want and where to look.
+
+All development (both new features and bugfixes) takes place in the `master` branch, it contains sources for the next
+version of Dokka.
+
+For any code changes:
+
+* Follow [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html).
+  Use 4 spaces for indentation.
+* [Build the project](#building) to make sure it all works and tests pass.
+* Write tests that reproduce the bug or test new features.
+* PRs without tests are accepted only in exceptional circumstances if it is evident that writing the
+  corresponding test is too hard or otherwise impractical.
+* If you add new or change old public API, [update public API dump](#updating-public-api-dump), otherwise it will fail 
+  the build.
+
+Please [contact maintainers](#contacting-maintainers) in advance to coordinate any big piece of work.
+
+### Building
+
+Building Dokka is pretty straightforward, with one small caveat: when you run `./gradlew build`, it will run integration
+tests as well, which might take some time and will consume a lot of RAM (~20-30 GB), so you would usually want to exclude 
+integration tests when building locally:
+
+```Bash
+./gradlew build -x integrationTest
+```
+
+Unit tests which are run as part of `build` should not take much time, but you can also skip it with `-x test`.
+
+### Using/testing locally built Dokka
+
+Below you will find a bare-bones instruction on how to use and test locally built Dokka. For more details and examples, 
+visit [Workflow](https://kotlin.github.io/dokka/1.7.20/developer_guide/workflow/) topic.
+
 1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version.
-   For example, you can set it to something like `1.7.20-my-fix-SNAPSHOT`.
-2. Publish it to maven local (`./gradlew publishToMavenLocal`)
-3. In the project you want to generate documentation for, add maven local as a plugin/dependency
+   For instance, you can set it to something like `1.7.20-my-fix-SNAPSHOT`.
+2. Publish it to Maven Local (`./gradlew publishToMavenLocal`)
+3. In the project for which you want to generate documentation add Maven Local as a buildscript/dependency
    repository (`mavenLocal()`)
-4. Update your dokka dependency to the version you've just published:
+4. Update your Dokka dependency to the version you've just published:
+
 ```kotlin
 plugins {
     id("org.jetbrains.dokka") version "1.7.20-my-fix-SNAPSHOT"
 }
 ```
+
+### Updating public API dump
+
+[Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) 
+is used to keep track of public API changes.
+
+Run `./gradlew apiDump` to update API index files after introducing new or changing old public API. Commit updated 
+API indexes together with other changes.
+
+## Contacting maintainers
+
+* If something cannot be done, not convenient, or does not work — submit an [issue](#submitting-issues).
+* Discussions and general inquiries — use `#dokka` channel in 
+  [Kotlin Community Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up).