diff --git a/README.md b/README.md
index 62e0b9b0..0080ea0b 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,35 @@
 
 Lightweight browser API bindings built around JS static interop.
 
-This package will *eventually* replace [`dart:html`](https://api.dart.dev/stable/dart-html/dart-html-library.html) and
-similar libraries in the Dart SDK to fully support WebAssembly.
+## What's this?
+
+This package exposes browser APIs. It's generated from the Web IDL definitions
+and uses recent Dart language features for zero-overhead bindings.
+
+This package is intended to replace
+[`dart:html`](https://api.dart.dev/stable/dart-html/dart-html-library.html) and
+similar Dart SDK libraries. It will support access to browser APIs from Dart
+code compiled to either JavaScript or WebAssembly.
+
+## Status
+
+The APIs in this package are still fairly provisional and could change rapidly.
+We'll continue to use [semantic versioning](https://semver.org/) as we evolve
+the APIs.
+
+## Usage
+
+```dart
+import 'package:web/web.dart';
+
+void main() {
+  final div = document.querySelector('div') as HTMLDivElement;
+  div.textContent = 'Text set at ${DateTime.now()}';
+}
+```
+
+## Web IDL version
 
 <!-- START updated by /tool/update_bindings.dart. Do not modify by hand -->
-Based on [`@webref/idl 3.39.1`](https://www.npmjs.com/package/@webref/idl/v/3.39.1)
+Based on [`@webref/idl 3.39.1`](https://www.npmjs.com/package/@webref/idl/v/3.39.1).
 <!-- END updated by /tool/update_bindings.dart. Do not modify by hand -->
diff --git a/tool/update_bindings.dart b/tool/update_bindings.dart
index 9fb8b893..d4bffc3e 100644
--- a/tool/update_bindings.dart
+++ b/tool/update_bindings.dart
@@ -93,8 +93,8 @@ ${RegExp.escape(_endComment)}
 
   final idlVersion = _webRefIdlVersion();
 
-  final idlReference =
-      'Based on [`$_webRefIdl $idlVersion`](https://www.npmjs.com/package/$_webRefIdl/v/$idlVersion)';
+  final idlReference = 'Based on [`$_webRefIdl $idlVersion`]'
+      '(https://www.npmjs.com/package/$_webRefIdl/v/$idlVersion).';
 
   final newContent = sourceContent.replaceFirst(replaceRegexp, '''
 $_startComment