Make a polishing pass and add placeholder for feature page

README.md

@@ -2,7 +2,7 @@
 
 [![a](https://img.shields.io/badge/slack-%23declarative_gradle-brightgreen?style=flat&logo=slack)](https://gradle.org/slack-invite)
 [![a](https://img.shields.io/badge/Getting-Started-blue?style=flat)](./docs/getting-started/README.md)
-[![a](https://img.shields.io/badge/Roadmap-Public-brightgreen?style=flat)](./ROADMAP.md)
+[![a](https://img.shields.io/badge/Roadmap-Public-brightgreen?style=flat)](./docs/ROADMAP.md)
 
 At Gradle, part of our vision is to provide an elegant and extensible declarative build language
 that enables expressing any build in a clear and understandable way.
@@ -62,7 +62,6 @@ As noted above, this syntax is experimental and might change during the experime
 The _Declarative Gradle_ experiment is still in an early stage but is ready for your feedback!
 
 * [Getting Started](docs/getting-started/README.md) - Learn how to try _Declarative Gradle_ yourself.
-* [Documentation](docs/README.md) - Learn about the fundamentals behind _Declarative Gradle_.
+* [Documentation](docs/reference/README.md) - Learn about the fundamentals behind _Declarative Gradle_.
 * [Participate](docs/CONTRIBUTING.md) - Learn how you can help shape the future of _Declarative Gradle_.
-* [Resources](publications/README.md) - Learn more from conferences, interviews, articles etc...
-* [Roadmap](ROADMAP.md) - Learn about what will come next.
+* [Resources](publications/README.md) - Learn more from conferences, interviews, articles, etc.

docs/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing to Declarative Gradle
 
 [![a](https://img.shields.io/badge/slack-%23declarative_gradle-brightgreen?style=flat&logo=slack)](https://gradle.org/slack-invite)
-[![a](https://img.shields.io/badge/Roadmap-Public-brightgreen?style=flat)](../ROADMAP.md)
+[![a](https://img.shields.io/badge/Roadmap-Public-brightgreen?style=flat)](./ROADMAP.md)
 
 _Declarative Gradle_ is an experimental project.
 Currently, it is not ready for tinkering or wide adoption.

docs/getting-started/README.md

@@ -1,14 +1,16 @@
 # Getting Started with Declarative Gradle
 
-In our first [announcement](https://blog.gradle.org/declarative-gradle), we talked about a new experimental project we called Declarative Gradle. That post introduced our ideas for a developer-first software definition and how we planned to create an elegant and declarative build language for Gradle. Since then, we've been working hard on several fronts to create the first early access preview (EAP) for Declarative Gradle.
+In our first [announcement](https://blog.gradle.org/declarative-gradle), we introduced our ideas for an experimental project we called Declarative Gradle. 
 
-!!! info
-    With this first EAP we would like you to try out what we have built so far and to give us [feedback](../CONTRIBUTING.md).
+Since then, we've been working hard on several fronts to create the first early access preview (EAP) for Declarative Gradle.
 
-    Declarative Gradle is **ready** for trying out sample repositories for Java, Kotlin and Android applications.
+!!! info
+    With the first EAP, we would like you to try out what we have built so far and to give us [feedback](../CONTRIBUTING.md).
 
-    Declarative Gradle is **not ready** for adoption in production by plugin authors, build engineers nor software engineers.
+    Declarative Gradle is **ready** for trying out our provided sample projects for Java, Kotlin and Android applications.
 
-* [Setup](./setup.md)
-* [Samples](./samples.md)
+    Declarative Gradle is **not ready** for adoption by plugin authors, build engineers or software engineers.
 
+1. Follow our [setup instructions](./setup.md)
+2. Pick one or more of our [samples](./samples.md)
+3. Try out the Declarative Gradle [features](./features.md)

docs/getting-started/features.md

@@ -0,0 +1,21 @@
+<!-- omit in toc -->
+# Features
+
+!!! tip
+    Check out the features below with one of our [samples](./samples.md). These features are guaranteed to work with them out of the box.
+
+## Declarative DSL in IDE
+
+TODO
+
+## Two-way editing
+
+TODO
+
+## Automated changes
+
+TODO
+
+## Software types and shared configuration
+
+TODO

docs/getting-started/samples.md

@@ -1,16 +1,17 @@
 <!-- omit in toc -->
 # Samples
+!!! tip
+    Make sure you followed the [setup](./setup.md) instructions fully before trying out a sample.
 
 All samples in this page can be used to demonstrate features made possible by Declarative Gradle.
 
 - [Java Application](#java-application)
 - [Kotlin Application](#kotlin-application)
 - [Android Application](#android-application)
 - [Now In Android](#now-in-android)
-- [Prototypes](#prototypes)
+- [Bleeding edge prototypes](#bleeding-edge-prototypes)
 
-!!! tip
-    Make sure you followed the [setup](./setup.md) instructions fully before trying out a sample.
+After picking a sample, read about new [Declarative Gradle features](./features.md).
 
 ## Java Application
 
@@ -38,9 +39,9 @@ The prototype repository can be found in [github.com/gradle/nowinandroid](https:
 
 Please follow the README available at [github.com/gradle/nowinandroid/DECLARATIVE-README.md](https://github.com/gradle/nowinandroid/blob/main-declarative/DECLARATIVE-README.md) to try this sample.
 
-## Prototypes
+## Bleeding edge prototypes
 
-If you want to go further you can take a look at some other prototypes for JVM, Android, KMP, Swift and C++ projects.
+If you want to go further you can take a look at some more projects for JVM, Android, KMP, Swift and C++ projects. These projects may use newer versions of Gradle or require additional manual setup, so you should try the other samples first. 
 
 They are available at [github.com/gradle/declarative-gradle/tree/main/unified-prototype](https://github.com/gradle/declarative-gradle/tree/main/unified-prototype).
 

docs/getting-started/setup.md

@@ -2,13 +2,14 @@
 # Setup
 
 Declarative Gradle [samples](./samples.md) require nightly versions of Gradle and Android Studio.
-They all use the [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html) to point to the right Gradle version so you don't have to worry about that.
+They all use the [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html) to point to the right Gradle version, so you don't have to worry about installing a specific version of Gradle.
 
-To try out the samples and be able to reproduce all features you need to install a few components as described below:
+To try out the samples and see all of the features, you need to install a few other components as described below:
 
 - [JDK](#jdk)
 - [Android Studio](#android-studio)
-- [Gradle Client](#gradle-client)
+- [Install the Gradle Client](#install-the-gradle-client)
+- [Pick a sample](#pick-a-sample)
 
 ## JDK
 
@@ -19,26 +20,32 @@ We recommend [Eclipse Temurin™ (OpenJDK)](https://adoptium.net/temurin/release
 
 ## Android Studio
 
-First, download and install the latest Android Studio Nightly.
+Download and install the latest Android Studio Nightly from the [Studio Nightly](https://developer.android.com/studio/nightly) official page.
 
-It can be found on the [Studio Nightly](https://developer.android.com/studio/nightly) official page.
-It can also be installed via the [JetBrains ToolBox](https://www.jetbrains.com/toolbox-app/) application.
+It can also be installed via the [JetBrains ToolBox](https://www.jetbrains.com/toolbox-app/).
+
+Declarative features are only available on the latest nightly releases.
 
 <!-- omit in toc -->
 ### Enable more declarative features in Studio
 
 !!! info
-    While syntax highlighting of `.gradle.dcl` files works out of the box in Studio nightlies, other features require to enable for flags.
+    While syntax highlighting of `.gradle.dcl` files works out of the box in Studio nightlies, other features require flags to be enabled.
 
 1. Open _Help -> Open Custom Vm Options_
 2. Add text `-Didea.is.internal=true`
 3. Restart the IDE
 4. Open _Tools -> Internal Actions -> Android -> Edit Studio Flags_ and type _"Gradle Declarative"_ in the search window
 5. Switch on the _Studio support for declarative files_ flags.
 
-## Gradle Client
+## Install the Gradle Client
 
 The _Gradle Client_ is a standalone application used to demonstrate declarative features not yet implemented in the IDE.
 
-Download the latest release from the [Gradle Client](https://github.com/gradle/gradle-client/releases) repository on GitHub and install it.
-A `DMG` file for Mac, a `DEB` file for Linux and a `MSI` file for Windows are attached to each release.
+Download the latest release from the [Gradle Client](https://github.com/gradle/gradle-client/releases/latest) repository on GitHub and install it.
+
+The `DMG` file is for macOS, the `DEB` file is for Linux and the `MSI` file is for Windows.
+
+## Pick a sample
+
+After you've installed everything, pick out a [samples](./samples.md) to try the Declarative Gradle features.

early-prototypes/single-target/README.md

@@ -18,6 +18,6 @@ Declares a few dependencies and the main class for a Java application.
 
 Declares a few dependencies for a Java library.
 
-### [Conventions](javalibrary/build-logic/src/main/kotlin/)
+### Conventions
 
-Sets up some common conventions for a Java application and library.
+`javalibrary/build-logic/src/main/kotlin` Sets up some common conventions for a Java application and library.

mkdocs.yml

@@ -38,7 +38,7 @@ theme:
     - content.tooltips
     # - header.autohide
     # - navigation.expand
-    - navigation.footer
+    # - navigation.footer
     # NOT compatible qith toc.integrate
     # - navigation.indexes
     - navigation.path
@@ -83,21 +83,20 @@ theme:
 nav:
   - Home:
     - Overview: README.md
-    - Roadmap: ROADMAP.md
   - Getting Started:
     - Overview: docs/getting-started/README.md
     - Setup: docs/getting-started/setup.md
     - Samples: docs/getting-started/samples.md
+    - Features: docs/getting-started/features.md
   - Documentation:
     - Overview: docs/reference/README.md
+    - Roadmap: docs/ROADMAP.md
     - Software Features: docs/reference/software-features.md
   - Participate:
     - Contributing: docs/CONTRIBUTING.md
     - Code of Conduct: docs/CODE_OF_CONDUCT.md
   - Resources:
     - Publications: publications/README.md
-    - KotlinConf 2024: publications/2024-05-kotlinconf.md
-    - Newsletter: publications/newsletter/README.md
 
 extra_css:
   - docs/assets/css/gradle.css

publications/README.md

@@ -15,11 +15,3 @@
 ](https://blog.gradle.org/declarative-gradle) by Piotr Jagielski - November 2023 - Initial project announcement and the manifesto
 - [Declarative Gradle? Amper? What’s going on?!](https://github.com/kotlin-magazine/kotlin-magazine/blob/main/articles/siggi_gunnarsson_declarative_builds_for_kotlin.md) by Siggi Gunnarsson, May 2024, [fun code() magazine](https://github.com/kotlin-magazine/kotlin-magazine)
 
-## Newsletter
-
-Starting from March 2024,
-we regularly publish updates on Declarative Gradle
-in the monthly [Gradle Build Tool Newsletter](https://newsletter.gradle.org/).
-Make sure to subscribe!
-
-[Learn More about the Newsletter](./newsletter/README.md)