Add Why Mill? top-level section to readme (#3870)

The goal is to be a single page to answer this frequently asked
question, skimming over and summarizing the interesting bits from the
other more-detailed pages in a way they are easily consumed in one
read-through.

For now it's mostly transcribed from my Japan Java User Group talk, and
very copy-pasty with other parts of the repo. Not perfect, but it can
evolve over time

docs/modules/ROOT/nav.adoc

@@ -3,108 +3,99 @@
 // but we intentionally skim over them and do not go into depth: the focus is
 // on end user goals and how to achieve them.
 
-.xref:index.adoc[]
-
-.xref:javalib/intro.adoc[]
-* xref:javalib/builtin-commands.adoc[]
-* xref:javalib/module-config.adoc[]
-* xref:javalib/dependencies.adoc[]
-* xref:javalib/testing.adoc[]
-* xref:javalib/linting.adoc[]
-* xref:javalib/publishing.adoc[]
-* xref:javalib/build-examples.adoc[]
-* xref:javalib/web-examples.adoc[]
-* xref:javalib/android-examples.adoc[]
-
-.xref:scalalib/intro.adoc[]
-* xref:scalalib/builtin-commands.adoc[]
-* xref:scalalib/module-config.adoc[]
-* xref:scalalib/dependencies.adoc[]
-* xref:scalalib/testing.adoc[]
-* xref:scalalib/linting.adoc[]
-* xref:scalalib/publishing.adoc[]
-* xref:scalalib/build-examples.adoc[]
-* xref:scalalib/web-examples.adoc[]
-
-.xref:kotlinlib/intro.adoc[]
-* xref:kotlinlib/builtin-commands.adoc[]
-* xref:kotlinlib/module-config.adoc[]
-* xref:kotlinlib/dependencies.adoc[]
-* xref:kotlinlib/testing.adoc[]
-* xref:kotlinlib/linting.adoc[]
-* xref:kotlinlib/publishing.adoc[]
-// * xref:kotlinlib/build-examples.adoc[]
-* xref:kotlinlib/web-examples.adoc[]
-* xref:kotlinlib/android-examples.adoc[]
-
-.Build Tool Comparisons
-* xref:comparisons/maven.adoc[]
-* xref:comparisons/gradle.adoc[]
-* xref:comparisons/sbt.adoc[]
-
-.The Mill CLI
-* xref:cli/installation-ide.adoc[]
-* xref:cli/flags.adoc[]
-* xref:cli/alternate-installation.adoc[]
-
+* xref:why-mill.adoc[]
+* xref:javalib/intro.adoc[]
+** xref:javalib/builtin-commands.adoc[]
+** xref:javalib/module-config.adoc[]
+** xref:javalib/dependencies.adoc[]
+** xref:javalib/testing.adoc[]
+** xref:javalib/linting.adoc[]
+** xref:javalib/publishing.adoc[]
+** xref:javalib/build-examples.adoc[]
+** xref:javalib/web-examples.adoc[]
+** xref:javalib/android-examples.adoc[]
+* xref:scalalib/intro.adoc[]
+** xref:scalalib/builtin-commands.adoc[]
+** xref:scalalib/module-config.adoc[]
+** xref:scalalib/dependencies.adoc[]
+** xref:scalalib/testing.adoc[]
+** xref:scalalib/linting.adoc[]
+** xref:scalalib/publishing.adoc[]
+** xref:scalalib/build-examples.adoc[]
+** xref:scalalib/web-examples.adoc[]
+* xref:kotlinlib/intro.adoc[]
+** xref:kotlinlib/builtin-commands.adoc[]
+** xref:kotlinlib/module-config.adoc[]
+** xref:kotlinlib/dependencies.adoc[]
+** xref:kotlinlib/testing.adoc[]
+** xref:kotlinlib/linting.adoc[]
+** xref:kotlinlib/publishing.adoc[]
+// ** xref:kotlinlib/build-examples.adoc[]
+** xref:kotlinlib/web-examples.adoc[]
+** xref:kotlinlib/android-examples.adoc[]
+* Build Tool Comparisons
+** xref:comparisons/maven.adoc[]
+** xref:comparisons/gradle.adoc[]
+** xref:comparisons/sbt.adoc[]
+* The Mill CLI
+** xref:cli/installation-ide.adoc[]
+** xref:cli/flags.adoc[]
+** xref:cli/alternate-installation.adoc[]
 // This section gives a tour of the various user-facing features of Mill:
 // library deps, out folder, queries, tasks, etc.. These are things that
 // every Mill user will likely encounter, and are touched upon in the various
 // language-specific sections, but here we go into a deeper language-agnostic
 // discussion of what these Mill features ar and how they work
-.Mill Fundamentals
-* xref:fundamentals/tasks.adoc[]
-* xref:fundamentals/modules.adoc[]
-* xref:fundamentals/out-dir.adoc[]
-* xref:fundamentals/query-syntax.adoc[]
-* xref:fundamentals/library-deps.adoc[]
-* xref:fundamentals/cross-builds.adoc[]
-* xref:fundamentals/bundled-libraries.adoc[]
-
+* Mill Fundamentals
+** xref:fundamentals/tasks.adoc[]
+** xref:fundamentals/modules.adoc[]
+** xref:fundamentals/out-dir.adoc[]
+** xref:fundamentals/query-syntax.adoc[]
+** xref:fundamentals/library-deps.adoc[]
+** xref:fundamentals/cross-builds.adoc[]
+** xref:fundamentals/bundled-libraries.adoc[]
 // This section talks about Mill plugins. While it could theoretically fit in
 // either section above, it is probably an important enough topic it is worth
 // breaking out on its own
-.Extending Mill
-* xref:extending/import-ivy-plugins.adoc[]
-* xref:extending/contrib-plugins.adoc[]
+* Extending Mill
+** xref:extending/import-ivy-plugins.adoc[]
+** xref:extending/contrib-plugins.adoc[]
 // See also the list in Contrib_Plugins.adoc
-** xref:contrib/artifactory.adoc[]
-** xref:contrib/bintray.adoc[]
-** xref:contrib/bloop.adoc[]
-** xref:contrib/buildinfo.adoc[]
-** xref:contrib/codeartifact.adoc[]
-** xref:contrib/docker.adoc[]
-** xref:contrib/flyway.adoc[]
-** xref:contrib/gitlab.adoc[]
-** xref:contrib/jmh.adoc[]
-** xref:contrib/playlib.adoc[]
-** xref:contrib/proguard.adoc[]
-** xref:contrib/scalapblib.adoc[]
-** xref:contrib/scoverage.adoc[]
-** xref:contrib/sonatypecentral.adoc[]
-** xref:contrib/testng.adoc[]
-** xref:contrib/twirllib.adoc[]
-** xref:contrib/versionfile.adoc[]
-* xref:extending/thirdparty-plugins.adoc[]
-* xref:extending/running-jvm-code.adoc[]
-* xref:extending/writing-plugins.adoc[]
-* xref:extending/meta-build.adoc[]
-* xref:extending/new-language.adoc[]
-
+*** xref:contrib/artifactory.adoc[]
+*** xref:contrib/bintray.adoc[]
+*** xref:contrib/bloop.adoc[]
+*** xref:contrib/buildinfo.adoc[]
+*** xref:contrib/codeartifact.adoc[]
+*** xref:contrib/docker.adoc[]
+*** xref:contrib/flyway.adoc[]
+*** xref:contrib/gitlab.adoc[]
+*** xref:contrib/jmh.adoc[]
+*** xref:contrib/playlib.adoc[]
+*** xref:contrib/proguard.adoc[]
+*** xref:contrib/scalapblib.adoc[]
+*** xref:contrib/scoverage.adoc[]
+*** xref:contrib/sonatypecentral.adoc[]
+*** xref:contrib/testng.adoc[]
+*** xref:contrib/twirllib.adoc[]
+*** xref:contrib/versionfile.adoc[]
+** xref:extending/thirdparty-plugins.adoc[]
+** xref:extending/running-jvm-code.adoc[]
+** xref:extending/writing-plugins.adoc[]
+** xref:extending/meta-build.adoc[]
+** xref:extending/new-language.adoc[]
 // This section focuses on diving into deeper, more advanced topics for Mill.
 // These are things that most Mill developers would not encounter day to day,
 // but people developing Mill plugins or working on particularly large or
 // sophisticated Mill builds will need to understand.
-.Mill In Depth
-* xref:depth/large-builds.adoc[]
-* xref:depth/sandboxing.adoc[]
-* xref:depth/evaluation-model.adoc[]
-* xref:depth/design-principles.adoc[]
-* xref:depth/why-scala.adoc[]
-
+* Mill In Depth
+** xref:depth/large-builds.adoc[]
+** xref:depth/sandboxing.adoc[]
+** xref:depth/evaluation-model.adoc[]
+** xref:depth/design-principles.adoc[]
+** xref:depth/why-scala.adoc[]
 // Reference pages that a typical user would not typically read top-to-bottom,
 // but may need to look up once in a while, and thus should be written down
 // *somewhere*.
-.Reference
-* {mill-doc-url}/api/latest/mill/index.html[Mill Scaladoc]
-* xref:reference/changelog.adoc[]
+* Reference
+** {mill-doc-url}/api/latest/mill/index.html[Mill Scaladoc]
+** xref:reference/changelog.adoc[]

docs/modules/ROOT/pages/index.adoc

@@ -70,15 +70,23 @@ xref:extending/writing-plugins.adoc#_publishing[publish them] to Maven Central f
 
 To begin using Mill, check out the introductory documentation for each language:
 
-* xref:javalib/intro.adoc[]
-* xref:scalalib/intro.adoc[]
-* xref:kotlinlib/intro.adoc[]
 
-If you prefer a video introduction, see the following tech talk that was presented
-at the Japan Java User Group Fall Conference Oct 2024:
+[cols="1a,1a,1a"]
+|===
+| xref:javalib/intro.adoc[image:index/iconscout-java.svg[java,32] Java with Mill]
+| xref:scalalib/intro.adoc[image:index/iconscout-scala.svg[scala,20] Scala with Mill]
+| xref:kotlinlib/intro.adoc[image:index/iconscout-kotlin.svg[kotlin,32] Kotlin with Mill]
+|===
 
-* https://www.youtube.com/watch?v=Dry6wMRN6MI[Video: Better Java Builds with the Mill Build Tool]
 
+For a quick introduction of why you may care about Mill, see the following page:
+
+* xref:why-mill.adoc[]
+
+Or if you prefer a video introduction:
+
+* https://www.youtube.com/watch?v=Dry6wMRN6MI[Video: Better Java Builds with the Mill Build Tool],
+  Japan Java User Group Fall Conference Oct 2024
 
 Mill is used to build many real-world projects, such as the
 https://github.com/swaldman/c3p0[C3P0 JDBC Connection Pool],
@@ -95,9 +103,15 @@ https://gradle.org/[Gradle], https://bazel.build/[Bazel], but tries to learn fro
 strengths of each tool and improve on their weaknesses. For comparisons with existing
 build tools, check out these pages:
 
-* xref:comparisons/maven.adoc[Mill vs Maven]
-* xref:comparisons/gradle.adoc[Mill vs Gradle]
-* xref:comparisons/sbt.adoc[Mill vs SBT]
+
+[cols="1a,1a,1a"]
+|===
+| xref:comparisons/maven.adoc[image:index/maven.png[maven,24] Mill vs Maven]
+| xref:comparisons/gradle.adoc[image:index/gradle.svg[gradle,32] Mill vs Gradle]
+| xref:comparisons/sbt.adoc[image:index/sbt.png[sbt,32] Mill vs SBT]
+|===
+
+
 
 If you want to contribute to Mill, or are interested in the fundamental ideas behind 
 Mill rather than the user-facing benefits discussed above, check out the page on