diff --git a/README.md b/README.md
new file mode 100644
index 0000000..66bad8c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,11 @@
+# paperweight-test-plugin
+
+jmp's test plugin for `paperweight-userdev` development
+
+(also serves as an example until more thorough documentation is created)
+
+### note
+
+- `build.gradle.kts` and `settings.gradle.kts` both contain important configuration.
+- `paperweight-userdev` automatically detects shadow and will use `shadowJar` as input for `reobfJar`. This means no extra configuration is required to use `paperweight-userdev` with shadow. See the `shadow` branch on this repository for an exmaple usage of shadow with `paperweight-userdev`.
+- The `plugin-yml` and `run-paper` Gradle plugins are both optional, however I use them in almost all my plugin projects and recommend at least trying them out. `plugin-yml` auto-generates your plugin.yml file from configuration in the build file, and `run-paper` allows for launching a test server with your plugin through the `runServer` and `runMojangMappedServer` tasks.
diff --git a/build.gradle.kts b/build.gradle.kts
index 909e401..b9792ad 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -4,7 +4,7 @@ plugins {
   `java-library`
   id("io.papermc.paperweight.userdev") version "1.3.1"
   id("xyz.jpenilla.run-paper") version "1.0.5" // Adds runServer and runMojangMappedServer tasks for testing
-  id("net.minecrell.plugin-yml.bukkit") version "0.5.0"
+  id("net.minecrell.plugin-yml.bukkit") version "0.5.1" // Generates plugin.yml
 }
 
 group = "io.papermc.paperweight"
@@ -12,31 +12,49 @@ version = "1.0.0-SNAPSHOT"
 description = "Test plugin for paperweight-userdev"
 
 java {
+  // Configure the java toolchain. This allows gradle to auto-provision JDK 17 on systems that only have JDK 8 installed for example.
   toolchain.languageVersion.set(JavaLanguageVersion.of(17))
 }
 
 dependencies {
   paperDevBundle("1.18-R0.1-SNAPSHOT")
+  // paperweightDevBundle("com.example.paperfork", "1.18-R0.1-SNAPSHOT")
+
+  // You will need to manually specify the full dependency if using the groovy gradle dsl
+  // (paperDevBundle and paperweightDevBundle functions do not work in groovy)
+  // paperweightDevelopmentBundle("io.papermc.paper:dev-bundle:1.18-R0.1-SNAPSHOT")
 }
 
 tasks {
-  // Run reobfJar on build
+  // Configure reobfJar to run when invoking the build task
   build {
     dependsOn(reobfJar)
   }
 
   compileJava {
-    options.encoding = Charsets.UTF_8.name()
+    options.encoding = Charsets.UTF_8.name() // We want UTF-8 for everything
+
+    // Set the release flag. This configures what version bytecode the compiler will emit, as well as what JDK APIs are usable.
+    // See https://openjdk.java.net/jeps/247 for more information.
     options.release.set(17)
   }
   javadoc {
-    options.encoding = Charsets.UTF_8.name()
+    options.encoding = Charsets.UTF_8.name() // We want UTF-8 for everything
   }
   processResources {
-    filteringCharset = Charsets.UTF_8.name()
+    filteringCharset = Charsets.UTF_8.name() // We want UTF-8 for everything
   }
+
+  /*
+  reobfJar {
+    // This is an example of how you might change the output location for reobfJar. It's recommended not to do this
+    // for a variety of reasons, however it's asked frequently enough that an example of how to do it is included here.
+    outputJar.set(layout.buildDirectory.file("libs/PaperweightTestPlugin-${project.version}.jar"))
+  }
+   */
 }
 
+// Configure plugin.yml generation
 bukkit {
   load = BukkitPluginDescription.PluginLoadOrder.STARTUP
   main = "io.papermc.paperweight.testplugin.TestPlugin"