Respond to doc review (#3845)

docs/modules/ROOT/pages/javalib/web-examples.adoc

@@ -1,4 +1,4 @@
-= Java Web Examples
+= Java Web Project Examples
 :page-aliases: Java_Web_Examples.adoc
 
 include::partial$gtag-config.adoc[]

docs/modules/ROOT/pages/kotlinlib/build-examples.adoc

@@ -17,3 +17,6 @@ include::partial$example/kotlinlib/builds/1-nested-modules.adoc[]
 
 include::partial$example/kotlinlib/builds/4-realistic.adoc[]
 
+== Example Builds for Real Projects
+
+TODO

docs/modules/ROOT/pages/kotlinlib/web-examples.adoc

@@ -1,4 +1,4 @@
-= Kotlin Web Examples
+= Kotlin Web Project Examples
 
 include::partial$gtag-config.adoc[]
 

docs/modules/ROOT/pages/scalalib/web-examples.adoc

@@ -1,4 +1,4 @@
-= Scala Web Examples
+= Scala Web Project Examples
 :page-aliases: Web_Build_Examples.adoc, Scala_Web_Examples.adoc
 
 include::partial$gtag-config.adoc[]

docs/modules/ROOT/partials/Intro_to_Mill_Header.adoc

@@ -10,7 +10,7 @@ digraph G {
     label = "foo";
 
     "foo.sources" -> "foo.compile" -> "foo.classPath" -> "foo.assembly"
-    "foo.mainClass" -> "foo.assembly"
+    "foo.resources" -> "foo.assembly"
     "foo.classPath"
   }
   subgraph cluster_1 {
@@ -21,18 +21,25 @@ digraph G {
     "foo.classPath" -> "bar.compile" [constraint=false]
     "foo.classPath" -> "bar.classPath"
     "bar.sources" -> "bar.compile" -> "bar.classPath" -> "bar.assembly"
-    "bar.mainClass" -> "bar.assembly"
+    "bar.resources" -> "bar.assembly"
   }
 }
 ```
 
-{mill-github-url}[Mill] is a fast multi-language JVM build tool that supports {language}, making your
-common development workflows xref:comparisons/maven.adoc[5-10x faster to Maven], or
-xref:comparisons/gradle.adoc[2-4x faster than Gradle], while providing better IDE support
-than xref:comparisons/maven.adoc#_extensibility_ide_experience[Maven],
-xref:comparisons/gradle.adoc#_ide_experience[Gradle] or xref:comparisons/sbt.adoc#_ide_support[SBT].
-Mill aims to make your JVM project's build process performant, maintainable, and flexible
-even as it grows from a small project to a large codebase or monorepo with hundreds of modules:
+Mill is a fast, scalable, multi-language JVM build tool that supports
+Java, Scala, and Kotlin:
+
+* Mill builds can compile the same codebase xref:comparisons/maven.adoc[5-10x faster than Maven],
+  or xref:comparisons/gradle.adoc[2-4x faster than Gradle]
+
+* Mill's typed, functional config language provides a richer IDE experience
+  than xref:comparisons/maven.adoc#_extensibility_ide_experience[Maven],
+  xref:comparisons/gradle.adoc#_ide_experience[Gradle] or xref:comparisons/sbt.adoc#_ide_support[SBT].
+
+* Mill scales well from small single-module projects
+  to xref:depth/large-builds.adoc[large monorepos] with hundreds of modules
+
+Mill achieves this via the following:
 
 * *Performance*: Mill's xref:fundamentals/tasks.adoc[build graph] automatically
   xref:depth/evaluation-model.adoc#_caching_at_each_layer_of_the_evaluation_model[caches]
@@ -42,17 +49,17 @@ even as it grows from a small project to a large codebase or monorepo with hundr
   and resolve bottlenecks in your build
 
 * *Maintainability*: Mill goes beyond YAML and Bash, with config and custom logic written in
-  xref:_custom_build_logic[concise type-checked code],
-  rather than shell scripts, XML or YAML. This lets IDEs
+  xref:_custom_build_logic[concise type-checked code]. This catches bugs and
+  config problems at compile time, and lets IDEs
   (xref:{language-small}lib/installation-ide.adoc#_intellij[IntelliJ] or
   xref:{language-small}lib/installation-ide.adoc#_vscode[VSCode])
-  understand and navigate around and refactor your build as easily as
+  understand and navigate around your build as easily as
   any application codebase.
 
-* *Flexibility*: Mill's custom tasks and modules allow anything from adding 
+* *Flexibility*: Mill's tasks and modules allow anything from adding
   xref:fundamentals/tasks.adoc#primitive-tasks[simple build steps], up to
   entire xref:extending/new-language.adoc[language toolchains].
-  You can xref:extending/import-ivy-plugins.adoc[import any JVM library] as part of your build,
+  You can xref:extending/import-ivy-plugins.adoc[import any JVM library] in your build,
   use Mill's rich ecosystem of xref:extending/thirdparty-plugins.adoc[Third-Party Mill Plugins],
   or xref:extending/writing-plugins.adoc[write plugins] yourself and
   xref:extending/writing-plugins.adoc#_publishing[publish them] to Maven Central for others to use.

example/scalalib/basic/1-simple/build.mill

@@ -26,7 +26,11 @@ object foo extends ScalaModule {
 // that you have some version of the JVM installed; the `./mill` script takes
 // care of any further dependencies that need to be downloaded. All examples
 // in this documentation site are executable and are continually exercised as 
-// part of Mill's CI workflows.
+// part of Mill's CI workflows, and they range from the simple hello-world
+// projects on this page to more sophisticated
+// xref:{language-small}lib/web-examples.adoc[web build examples] or
+// xref:{language-small}lib/build-examples.adoc#_example_builds_for_real_projects[example
+// builds for real-world projects]
 //
 // The source code for this module lives in the `src/` folder.
 // Output for this module (compiled files, resolved dependency lists, ...)

example/scalalib/basic/2-custom-build-logic/build.mill

@@ -62,33 +62,22 @@ Inputs:
 
 // Above, `def lineCount` is a new build task we define, which makes use of
 // `allSourceFiles` (an existing task) and is in-turn used in our override of
-// `resources` (also an existing task). This generated file can then be
-// loaded and used at runtime, as see in the output of `mill run`.
+// `resources` (also an existing task). The `override` keyword is optional in Mill.
+// This generated file can then be loaded and used at runtime, as see in the output
+// of `mill run`.
 //
-//  `os.read.lines` and `os.write` come
+// If you're not familiar with what tasks you can `override` or how they are related,
+// you can explore the existing tasks via autocomplete in your IDE, or use the
+// xref:{language-small}lib/builtin-commands.adoc#_visualize[mill visualize].
+//
+// `os.read.lines` and `os.write` come
 // from the https://github.com/com-lihaoyi/os-lib[OS-Lib] library, which is
 // one of Mill's xref:fundamentals/bundled-libraries.adoc[Bundled Libraries].
 // You can also import any other library you want from Maven Central using
 // xref:extending/import-ivy-plugins.adoc[import $ivy], so you are not limited
 // to what is bundled with Mill.
 //
-// If you're not familiar with what existing tasks are available to override and
-// how they interact with one another, you can explore them via autocomplete or
-// jump-to-definition in your IDE, or use the
-// xref:{language-small}lib/builtin-commands.adoc#_visualize[mill visualize] command.
-//
-// While this is a toy example, it shows how easy it is to customize your Mill
-// build to include the kinds of custom logic common in the build config of
-// most real-world projects.
-//
-// This customization is done in a principled fashion familiar to most
-// programmers - `override` and `super` - rather than ad-hoc
-// monkey-patching or mutation common in other build tools. You never have
-// "spooky action at a distance" affecting your build / graph definition, and
-// your IDE can always help you find the final override of any particular build
-// task as well as where any overriden implementations may be defined.
-//
-// Unlike normal methods, custom user-defined tasks in Mill benefit from all
+// Custom user-defined tasks in Mill benefit from all
 // the same things that built-in tasks do: automatic caching (in the
 // xref:fundamentals/out-dir.adoc[out/ folder]), parallelism (with the xref:#_parallel_task_execution[-j/--jobs
 // flag]), inspectability (via xref:{language-small}lib/builtin-commands.adoc#_show[show]/xref:{language-small}lib/builtin-commands.adoc#_inspect[inspect]), and so on.