lead with a more complete example in the readme

src/_includes/partials/description.md

@@ -1,9 +1,42 @@
 <section class="kdl-section" id="description">
 
-KDL is a document language with xml-like semantics that looks like you're
+KDL is a small, pleasing document language with xml-like semantics that looks
-invoking a bunch of CLI commands! It's meant to be used both as a
+like you're invoking a bunch of CLI commands! It's meant to be used both as a
 serialization format and a configuration language, much like JSON, YAML, or
-XML.
+XML. It looks like this:
+
+```kdl
+package {
+  name "my-pkg"
+  version "1.2.3"
+
+  dependencies {
+    // Nodes can have standalone values as well as key/value pairs.
+    lodash "^3.2.1" optional=true alias="underscore"
+  }
+
+  scripts {
+    // "Raw" and multi-line strings are supported.
+    build r#"
+      echo "foo"
+      node -c "console.log('hello, world!');"
+      echo "foo" > some-file.txt
+    "#
+  }
+
+  // `\` breaks up a single node across multiple lines.
+  the-matrix 1 2 3 \
+             4 5 6 \
+             7 8 9
+
+  // "Slashdash" comments operate at the node level, with just `/-`.
+  /-this-is-commented {
+    this "entire" "node" {
+      "is" "gone"
+    }
+  }
+}
+```
 
 There's a living [specification](https://github.com/kdl-org/kdl/blob/main/SPEC.md), as well as various
 [implementations](#implementations). You can also check out the [FAQ](#faq) to