Added some documentation

Author: ubiratansoares

.github/assets/magicmodules-demo.gif

@@ -1,8 +1,209 @@
 # Magic Modules
+![Main workflow](https://github.com/dotanuki-labs/magic-modules/workflows/Main%20workflow/badge.svg)
+
+![](.github/assets/magicmodules-demo.gif)
 
 ## What is this?
 
-WIP
+> // Blog post with the full motivation to come! Stay tunned
+
+For large Android projects hosted in mono repos, management for module names might be a real pain, specially when we have lots of moving parts under a structure driven by nested Gradle subprojects.
+
+This experimental plugin attemps to solve that. It parses a project tree like this
+
+```
+.
+├── app
+│   └── src
+│       └── main
+│           ├── AndroidManifest.xml
+│           ├── java
+│           └── res
+├── build.gradle
+├── buildSrc
+│   ├── build.gradle.kts
+│   └── src
+│       └── main
+│           └── kotlin
+├── common
+│   ├── core
+│   │   ├── build.gradle
+│   │   └── src
+│   │       └── main
+│   └── utils
+│       ├── build.gradle.kts
+│       └── src
+│           └── main
+├── features
+│   ├── home
+│   │   ├── build.gradle
+│   │   └── src
+│   │       └── main
+│   └── login
+│       ├── build.gradle
+│       └── src
+│           └── main
+|
+|
+└── settings.gradle
+
+```
+
+and
+
+- it automatically includes all founded modules in `settings.gradle`
+- it writes 2 Kotlin files under your `buildSrc/src/main/kotlin` : 
+
+```kotlin
+// Generated by MagicModules plugin. Mind your Linters!
+import kotlin.String
+import kotlin.collections.List
+
+object Libraries {
+    const val FEATURES_HOME: String = ":features:home"
+
+    const val FEATURES_LOGIN: String = ":features:login"
+
+    const val COMMON_CORE: String = ":common:core"
+
+    const val COMMON_UTILS: String = ":common:utils"
+
+    val allAvailable: List<String> = 
+            listOf(
+                FEATURES_HOME,
+                FEATURES_LOGIN,
+                COMMON_CORE,
+                COMMON_UTILS
+            )
+}
+```
+
+and
+
+```kotlin
+// Generated by MagicModules plugin. Mind your Linters!
+import kotlin.String
+import kotlin.collections.List
+
+object Applications {
+    const val APP: String = ":app"
+
+    val allAvailable: List<String> = 
+            listOf(
+                APP
+            )
+}
+```
+In this way, refactors around the project structure will become a bit easier, since `build.gradle` configuration
+
+```groovy
+dependencies {
+    implementation project(Libraries.COMMON_UTILS)
+    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
+    implementation ...
+}
+```
+
+will break if `common/utils` moves around. The new constant under `buildSrc` will be mapped and will be ready to use.
+
+We can also add all the libraries to one monotlithic app easily
+
+```groovy
+dependencies {
+    Libraries.allAvailable.each { implementation project(it) }
+}
+```
+
+## Setup
+
+Add this snippet in your `settings.gradle` file
+
+```groovy
+buildscript {
+    repositories {
+        maven { url 'https://jitpack.io' }
+    }
+
+    dependencies {
+        classpath 'io.labs.dotanuki:magic-modules-plugin:<plugin_version>'
+    }
+}
+
+apply plugin: "io.labs.dotanuki.magicmodules"
+
+```
+
+and remove all `include` statements
+
+```groovy
+include 'app'
+include 'featureA'
+include 'featureB'
+include 'featureC'
+include ...
+
+```
+They are not needed anymore.
+
+If your project uses a multi-application layout, with standalone apps for your features/screens, you can opt-in to not include all `com.android.application` modules in order to reduce configuration times locally and eventually build times on CI.
+
+```groovy
+rootProject.name='awesome-project'
+
+apply plugin: "io.labs.dotanuki.magicmodules"
+
+magicModules {
+    includeApps = false
+}
+
+include ':app'
+
+```
+
+## Matching Gradle build files
+
+This plugin walks your project tree and inspect all the `build.gradle` and `build.gradle.kts` files in order to learn if the related module matches an Android/JVM library or an Android application. This means that this plugin is sensitive on how you apply plugins in your `build.gradle` files
+
+```groovy
+apply plugin: 'com.android.library'
+```
+
+or 
+
+```kotlin
+plugins {
+    kotlin("jvm")
+}
+```
+
+This plugin does a best-effort attempt in order to catch all the common cases, but it might not work at all if you (1) have some strategy to share build logic accross Gradle modules and (2) define the applied plugin using such shared build logic
+
+## Building and testing
+
+To build this plugin and publish it locally for testing
+
+```shell
+./gradlew publishToMavenLocal
+```
+
+To run all the checks, including integration tests
+
+```shell
+./gradlew ktlintCheck test
+```
+
+## Limitations
+
+The main limitation I've found with this approach is that - right now - the plugin generates the `Libraries.kt` and `Applications.kt` under the main source set of `buildSrc`, which means that eventually issues with Git and/or linters that run for `buildSrc` files.
+
+I needed more work in order to figure out if we can have such generated files under `buildSrc/build` somehow.
+
+## Further work
+
+I realised that
+
+- It might be useful to configure the output folder/package for `Libraries.kt` and `Applications.kt`
+- It might be useful to grab more Gradle build script matchers using the plugin configuration
 
 ## Author