diff --git a/example/README.md b/example/README.md
new file mode 100644
index 0000000000..c6d814e8eb
--- /dev/null
+++ b/example/README.md
@@ -0,0 +1,33 @@
+# dartdoc examples
+
+Dartdoc is typically used as a command line utility to support generating
+documentation served on websites.  In the future this directory may contain
+direct examples, but for now, here are pointers to the main users of dartdoc
+in the Dart ecosystem.
+
+## Dart SDK
+
+The Dart team builds docs for the [Dart API reference](https://api.dart.dev/)
+with each new version of the SDK, via
+[this script](https://github.com/dart-lang/sdk/blob/master/tools/bots/dart_sdk.py).
+Look for `BuildDartdocAPIDocs`.
+
+## Flutter
+
+The Flutter team builds [API documentation for the Flutter SDK](https://api.flutter.dev)
+automatically.  A [shell script](https://github.com/flutter/flutter/blob/master/dev/bots/docs.sh)
+wraps a [small dart program](https://github.com/flutter/flutter/blob/master/dev/tools/dartdoc.dart)
+that manages the process.
+
+## pub
+
+The [pub package website](https://pub.dev) automatically builds Dart
+[API documentation](https://pub.dev/documentation/dartdoc/latest/)
+for [uploaded packages](https://pub.dev/packages/dartdoc).
+
+Note, unlike the other two examples, here dartdoc is used as a library.  While we make some
+effort not to regularly break simple uses of the library interface, we strongly recommend
+you use the command line and focus our semantic versioning around that case.   However, if
+that doesn't work for your case, the pub site usage may be of interest.  See
+[this script](https://github.com/dart-lang/pub-dev/blob/master/pkg/pub_dartdoc/bin/pub_dartdoc.dart)
+for the entry point.
\ No newline at end of file
diff --git a/pubspec.yaml b/pubspec.yaml
index 4d24979772..bf037d19a5 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -2,7 +2,7 @@ name: dartdoc
 # Run `grind build` after updating.
 version: 0.29.1
 author: Dart Team <misc@dartlang.org>
-description: A documentation generator for Dart.
+description: A non-interactive HTML documentation generator for Dart source code.
 homepage: https://github.com/dart-lang/dartdoc
 environment:
   sdk: '>=2.6.0 <3.0.0'
diff --git a/test/package_meta_test.dart b/test/package_meta_test.dart
index dd231b65d7..678dd0ee9d 100644
--- a/test/package_meta_test.dart
+++ b/test/package_meta_test.dart
@@ -46,7 +46,10 @@ void main() {
     });
 
     test('has a description', () {
-      expect(p.description, equals('A documentation generator for Dart.'));
+      expect(
+          p.description,
+          equals(
+              'A non-interactive HTML documentation generator for Dart source code.'));
     });
 
     test('has a homepage', () {