rewrite readme

README.md

@@ -1,34 +1,55 @@
 # Quilt Mappings
 
-Quilt Mappings is a set of open, unencumbered Minecraft mappings, free for everyone to use under the Creative Commons Zero license. The intention is to let 
-everyone mod Minecraft freely and openly, while also being able to innovate and process the mappings as they see fit.
+Quilt Mappings is a set of open, accurate, and easy-to-understand Minecraft mappings
+under the Creative Commons Zero license. Quilt Mappings seeks to provide the best of
+both worlds in terms of mapping quality: the accuracy and completeness of Mojang's
+official mappings, and the simplicity and set-in-stone conventions of its basis, the
+[Yarn](https://github.com/fabricmc/yarn) project.
 
-To see the current version being targeted, check the branch name!
+Quilt Mappings exists to provide a stable set of mappings for everyone to contribute
+and improve upon. We provide mappings for all versions of Minecraft from 1.17 onwards.
+To see what version is currently being targeted for updates, check the current Git branch's name.
 
-## Usage
-To use Quilt Mappings-deobfuscated Minecraft for Minecraft modding or as a dependency in a Java project, you can use [quilt-gradle](https://github.com/quiltmc/quilt-gradle) Gradle plugin. See [fabric wiki tutorial](https://fabricmc.net/wiki/tutorial:setup) for more information.
+## Using QM
 
-To obtain a deobfuscated Minecraft jar, [`./gradlew mapNamedJar`](#mapNamedJar) will generate a jar named like `<minecraft version>-named.jar`, which can be sent to a decompiler for deobfuscated code.
+To use Quilt Mappings in your mod, you can use either [quilt-loom](https://github.com/quiltmc/quilt-loom)
+for Quilt mods or use our Intermediary publication on [Fabric's loom](https://github.com/fabricmc/fabric-loom)
+for Fabric mods. We recommend cloning the [Quilt Template Mod](https://github.com/quiltmc/quilt-template-mod)
+to start a new mod with QM, and you can also add this block to your `build.gradle` inside the `dependencies` block:
 
-Please note to run the Quilt Mappings build script **Java 17** or higher is required!
+```groovy
+mappings("org.quiltmc:quilt-mappings:[version]:intermediary-v2")
+```
 
-## Contributing
+Note that on `fabric-loom`, you'll have to add the following to your `repositories` block as well, to tell gradle
+where to find the QM publication:
 
-Our goal is to provide high-quality names that make intuitive sense. In our experience, this goal is best achieved through contribution of original names, rather than copying names from other mappings projects. While we believe that discussions relating to the names used by other mappings projects can be useful, those names must stand up to scrutiny on their own - we won't accept names on the grounds that they're present in other mappings projects. 
+```groovy
+maven { url = "https://maven.quiltmc.org/repository/release/" }
+```
 
-We recommend discussing your contribution with other members of the community - either directly in your pull request, or in our other community spaces. We're always happy to help if you need us!
+QM versions are named after the Minecraft version they target, followed by `+build.x`,
+with `x` being a number that increments with each new build of QM for that Minecraft version.
+For example, `1.18.2+build.1` is the first build of QM for Minecraft `1.18.2`. You can see additional
+information and see what the latest QM build for each Minecraft version is with [LambdAurora's import tool](https://lambdaurora.dev/tools/import_quilt.html).
 
-Please have a look at the [naming conventions](/CONVENTIONS.md) before submitting mappings.
+## Contributing to QM
 
-### Getting Started
+When contributing names, the primary goal you should keep in mind is their intuitiveness:
+if you read this name with no context other than its declaration, would you know what it does?
+If not, the name either needs to be rethought or given javadocs if a good name can't be found.
 
-1. Fork and clone the repo
-2. Run `./gradlew mappings` (Linux, macOS) or `gradlew mappings` (Windows) to open [Enigma](https://github.com/QuiltMC/Enigma), a user interface to easily edit the mappings
-3. Commit and push your work to your fork
-4. Open a pull request with your changes
+We recommend coming up with original names as often as possible. In the case that something is too
+difficult to understand or name, check Mojang and Yarn's mappings for inspiration! Always spend some
+time thinking of original names before you make the decision to match theirs. For original names, it's
+best to check Mojang and Yarn anyway to make sure your name is correct - it's easy to make mistakes!
 
-## Gradle
-Quilt Mappings uses Gradle to provide a number of utility tasks for working with the mappings.
+In order to get started with making your first pull request, 
+please see the guide in [CONTRIBUTING.md](CONTRIBUTING.md#guide-pull-requests)!
+
+## Gradle Tasks
+
+QM has a set of helpful Gradle tasks to make mapping easier, including:
 
 ### `mappings`
 Setup and download and launch the latest version of [Enigma](https://github.com/QuiltMC/Enigma) automatically configured to use the merged jar and the mappings.
@@ -54,4 +75,4 @@ Downloads the client and server Minecraft jars for the current Minecraft version
 ### `mergeJars`
 
 Merges the client and server jars into one merged jar, located at `VERSION-merged.jar` in the project directory
-where `VERSION` is the current Minecraft version.
+where `VERSION` is the current Minecraft version.