diff --git a/README.MD b/README.MD
deleted file mode 100644
index 8f837fb2d..000000000
--- a/README.MD
+++ /dev/null
@@ -1,75 +0,0 @@
-# Scaladex
-
-[](https://travis-ci.org/scalacenter/scaladex)
-[](https://gitter.im/scalacenter/scaladex)
-
-Scaladex is the website where all the open source Scala libraries are indexed.
-
-## Acknowledgments
-
-
-
-This project is funded by the Scala Center.
-
-## How it works
-
-We pull poms from Bintray and we receive poms from Maven Central (Sonatype).
-Your library has to be published to one of those repositories.
-
-* [`How to publish on Maven Central`](/doc/user/publish-maven-central.md)
-* [`How to publish on Bintray`](/doc/user/publish-bintray.md)
-
-You can also watch [The Last 10 Percent by Stefan Zeiger](https://www.youtube.com/watch?v=RmEMUwfQoSc).
-
-Process:
-* Sources of artifacts
- * Push from Maven Central (Sonatype):
- * We receive pushes from Maven Central that follow the scala artifactId convention.
- A common practice is to include the scala compiler version in the artifactId.
- The `.pom files` will contain `_2.10`, `_2.11`, `_2.12` or any further Scala Version.
- * Pull Bintray (once per day):
- * File Search: artifacts that follow the scala artifactId convention presented above.
- * Non Standards: If you dont follow this convention add your artifacts to [non-standard.json]
- * Sbt Plugins: We index sbt plugins published to [sbt/sbt-plugin-releases] add your plugin to [claims.json]
-* We download pom and parent poms
-* We read them, 10% are invalid
- (most common issue: duplicated tags see https://github.com/sbt/sbt/issues/2566)
-* We inspect the pom file for scm tag (source control management).
- If you forgot to add a scm tag claim your library or you publish a sbt plugin add claim your project to [claims.json]
-* We download content and metadata from GitHub (Readme, Avatar, Descriptions, etc)
-
-[non-standard.json]: https://github.com/scalacenter/scaladex-data/blob/master/non-standard.json
-[sbt/sbt-plugin-releases]: https://bintray.com/sbt/sbt-plugin-releases
-[claims.json]: https://github.com/scalacenter/scaladex-data/blob/master/claims.json
-## How to contribute
-
-Join the [gitter.im channel](https://gitter.im/scalacenter/scaladex) and
-read the [developer guide](/CONTRIBUTING.md)
-
-## Badges API
-
-### Show the versions of Scala supported by your project!
-
-You can add this badge to the README.MD of your own GitHub projects to show
-the versions of Scala they support:
-
-[](https://index.scala-lang.org/typelevel/cats/cats-core)
-
-...the badge above only summarises latest JVM artifacts, if you'd like a badge
-for Scala JS or Scala Native, add a `targetType=...` query-string parameter:
-
-[](https://index.scala-lang.org/typelevel/cats/cats-core)
-
-[](https://index.scala-lang.org/typelevel/cats/cats-core)
-
-### Smaller, shorter badges
-
-[](https://index.scala-lang.org/search?q=dependencies:typelevel/cats)
-
-[](https://index.scala-lang.org/typelevel/cats/cats-core)
-
-[](https://index.scala-lang.org/search?q=dependencies:akka/*)
-
-[](https://index.scala-lang.org/akka/akka/akka-http-core)
-
-For more information read the [shields.io API](http://shields.io/)
diff --git a/README.md b/README.md
new file mode 100644
index 000000000..91158f3ff
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# Scaladex
+
+
+[](https://gitter.im/scalacenter/scaladex)
+
+Scaladex is the website where the open source Scala libraries are indexed.
+Its main purpose is to help Scala developers find useful libraries and to help library authors promote their libraries and find new contributors.
+
+## Acknowledgments
+
+
+
+This project is funded by the Scala Center.
+
+## How it works
+
+Scaladex receives poms automatically from Maven Central (Sonatype) based on the binary version of the artifact ID.
+Some valid Scala binary versions are `_2.13`, `_3`, `_sjs1_3`, `_native0.6_2.13`, `_2.12_1.0`.
+
+Checkout how to publish to Maven Central with sbt and Mill:
+- [Publish with sbt](https://www.scala-sbt.org/1.x/docs/Publishing.html)
+- [Automated publish with sbt](https://github.com/sbt/sbt-ci-release)
+- [Publish with Mill](https://com-lihaoyi.github.io/mill/mill/Intro_to_Mill.html#_deploying_your_code)
+
+You can also watch [The Last 10 Percent by Stefan Zeiger](https://www.youtube.com/watch?v=RmEMUwfQoSc).
+
+Scaladex associates a new artifact to a project by looking at the `scm` (Source Code Management) attribute in the pom file.
+At the moment Scaladex only supports Github repositories.
+
+The description of a project (its readme, its avatar, its website link...) are automatically downloaded from Github.
+
+## Troubleshooting
+
+### My project is missing or some artifacts are missing
+
+1. Did you publish the artifacts to Maven Central release?
+2. What is the binary version of your artifacts?
+
+If your artifact does not have any binary version it is considered a Java artifact and it will not be automatically indexed.
+Yet some Java artifact are closely related to Scala.
+In that case you can force its indexing by updating the [non-standard.json](https://github.com/scalacenter/scaladex-contrib/blob/master/non-standard.json) file in the [scaladex-contrib](https://github.com/scalacenter/scaladex-contrib) repository.
+
+At the moment we don't support full Scala binary versions, that are often used in Scala compiler plugins.
+If your project only contains artifacts with full Scala binary versions it cannot be indexed in Scaladex.
+
+3. Does the pom file contain the `scm` attribute and does it points to a public Github repository?
+
+If not you can claim that the artifact belongs to your Github repository by updating the [claims.json](https://github.com/scalacenter/scaladex-contrib/blob/master/claims.json) file in the [scaladex-contrib](https://github.com/scalacenter/scaladex-contrib) repository.
+
+If your project is not hosted by Github you should consider creating a mirror of it in Github.
+
+Do not forget to update the `scmInfo` setting in your build file before the next release.
+
+### My project is hard to find in the search page
+
+Read [How to improve the visibility of your project](doc/user/improve-visibility.md).
+
+## How to contribute
+
+Join the [gitter.im channel](https://gitter.im/scalacenter/scaladex) and read the [Contributing Guide](/CONTRIBUTING.md)
+
+## Badges
+
+### Show the versions of Scala supported by your project!
+
+You can add this badge to the README.MD of your own GitHub projects to show
+the versions of Scala they support:
+
+[](https://index.scala-lang.org/typelevel/cats/cats-core)
+
+...the badge above only summarises latest JVM artifacts, if you'd like a badge
+for Scala JS or Scala Native, add a `targetType=...` query-string parameter:
+
+[](https://index.scala-lang.org/typelevel/cats/cats-core)
+
+[](https://index.scala-lang.org/typelevel/cats/cats-core)
+
+### Smaller, shorter badges
+
+[](https://index.scala-lang.org/typelevel/cats/cats-core)
+
+[](https://index.scala-lang.org/akka/akka/akka-http-core)
+
+For more information read the [shields.io API](http://shields.io/)
diff --git a/doc/user/improve-visibility.md b/doc/user/improve-visibility.md
index 6597f1d22..235ec3012 100644
--- a/doc/user/improve-visibility.md
+++ b/doc/user/improve-visibility.md
@@ -2,7 +2,9 @@
As a library author or maintainer, the visibility of your project on Scaladex is under your control.
-As soon as an artifact is pushed to Maven Central (Sonatype), Scaladex downloads the `pom.xml` from Maven Central and the repository metadata from Github. The following properties are taken into account by the search algorithm, with corresponding boost. The bigger is the boost, the more importance is attributed to the property.
+As soon as an artifact is pushed to Maven Central (Sonatype), Scaladex downloads the `pom.xml` from Maven Central and the repository metadata from Github.
+The following properties are taken into account by the search algorithm, with corresponding boost.
+The bigger is the boost, the more important the property.
| property | boost |
@@ -14,16 +16,20 @@ As soon as an artifact is pushed to Maven Central (Sonatype), Scaladex downloads
| name of the artifacts in Maven Central| 2 |
| project README on Github | 0.5 |
-You can make it easier for a user to discover your project by paying attention to the below details:
+You can make it easier for a user to find your project by paying attention to the below details:
### Meaningful Github description
-A good description is short but meaningful. keep in mind that those words are the first words a user will read about your project.
+A good description is short but meaningful.
+Keep in mind that those words are the first words a user will read about your project.
### Precise Github topics
-Carefully choosing the topics of your project is the most efficient way to improve your discoverability. You should ask yourself what terms a developer is likely to type when looking for a solution that your library provides. Be precise. If your project is a collection of utilities the term `utils` is not much helpful but `time`, `duration`, `units`, `hashing` are.
+Carefully choosing the topics of your project is the most efficient way to improve your discoverability.
+You should ask yourself what terms a developer is likely to type when looking for a solution that your library provides.
+Be precise.
+If your project is a collection of utilities the term `utils` is not much helpful but `time`, `duration`, `units`, `hashing` are.
### Detailed README
-A detailed readme is helpful but it is not required for good indexing.
\ No newline at end of file
+A detailed readme is helpful but it is not required for good indexing.
diff --git a/doc/user/publish-bintray.md b/doc/user/publish-bintray.md
deleted file mode 100644
index dc5562c37..000000000
--- a/doc/user/publish-bintray.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# How to publish on Bintray
-
-First time:
-
-0. [create a Bintray account](https://bintray.com/signup/index)
-1. get your api key (SHA1) at [profile/edit](https://bintray.com/profile/edit) (it look like this: da39a3ee5e6b4b0d3255bfef95601890afd80709)
-2. add [sbt-bintray] to a project
-3. set your user and api key with `sbt bintrayChangeCredentials`
-
-For each project:
-
-0. add [sbt-bintray] to your project.
-1. set a license (ex: `licenses := Seq("MIT" -> url("http://www.opensource.org/licenses/mit-license.html"))`)
-
-See sbt-bintray [publishing documentation](https://github.com/sbt/sbt-bintray#publishing) for other available settings.
-
-For each artifact:
-
-0. `sbt publish`
-
-## Sbt Plugins
-
-http://www.scala-sbt.org/release/docs/Bintray-For-Plugins.html
-
-[sbt-bintray]: https://github.com/sbt/sbt-bintray
diff --git a/doc/user/publish-maven-central.md b/doc/user/publish-maven-central.md
deleted file mode 100644
index 58f57c8e7..000000000
--- a/doc/user/publish-maven-central.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# How to publish on Maven Central
-
-First time:
-
-0. Create [JIRA account](https://issues.sonatype.org/secure/Signup!default.jspa)
-1. Install `gpg` e.g. on OSX: `brew install gpg`
-2. Run `gpg --gen-key` to generate a new key. Remember the passphrase you used.
-3. Publish your public-key you created above e.g. `gpg --keyserver hkp://pgp.mit.edu --send-keys 433884a7dae3eb82`
-
-For each project:
-
-0. Create [new JIRA issue](https://issues.sonatype.org/secure/CreateIssue.jspa?issuetype=21&pid=10134) using above account to request new repo
-1. Wait till [above issue](https://issues.sonatype.org/browse/OSSRH-18266?filter=-2) is resolved
-2. Add `sbt-pgp`, `sbt-release` and `sbt-sonatype` as a plugin to your project. Here is an example [plugins.sbt](https://github.com/pathikrit/better-files/blob/master/project/plugins.sbt)
-3. Here is an example [build.sbt](https://github.com/pathikrit/better-files/blob/master/build.sbt) that I use for multi-projects
-
-For each artifact:
-
-0. `sbt release` (will prompt for passphrase)
-1. View artifact here: https://oss.sonatype.org/content/repositories/releases/
-
-source: https://gist.github.com/pathikrit/6a49de2489e53876679b
\ No newline at end of file