diff --git a/sdk/api_readme.md b/sdk/api_readme.md
index c7239902b14..3e5990dd3d9 100644
--- a/sdk/api_readme.md
+++ b/sdk/api_readme.md
@@ -1,31 +1,32 @@
-Welcome to the Dart API reference documentation, covering the official Dart API
+Welcome to the Dart API reference documentation, covering the core Dart API
 libraries. Some of the most fundamental Dart libraries include:
    
-  * [dart:core](dart-core/dart-core-library.html): Core functionality such as strings, numbers, collections, errors, dates, and URIs.
-  * [dart:html](dart-html/dart-html-library.html): DOM manipulation for web apps.
-  * [dart:io](dart-io/dart-io-library.html): I/O for command-line apps.
+  * [dart:core](dart-core/dart-core-library.html): Core functionality such as
+    strings, numbers, collections, errors, dates, and URIs.
+  * [dart:html](dart-html/dart-html-library.html): DOM manipulation for web apps
+    (available only to web apps).
+  * [dart:io](dart-io/dart-io-library.html): I/O for non-web apps.
   
 Except for `dart:core`, you must import a library before you can use it. Here's
-an example of importing `dart:html` and `dart:math`:
+an example of importing `dart:async` and `dart:math`:
 
 ```dart
-import 'dart:html';
+import 'dart:async';
 import 'dart:math';
 ```
 
-You can install more libraries using the pub package manager. For information
-on finding, using, and publishing libraries with pub, see 
-[pub.dartlang.org](https://pub.dartlang.org).
+You can install more libraries using the
+[pub package manager](https://www.dartlang.org/tools/pub).
   
 The main site for learning and using Dart is
-[www.dartlang.org](https://www.dartlang.org). Check out these additional pages:
+[www.dartlang.org](https://www.dartlang.org). Check out these pages:
   
-  * [Tutorials](https://www.dartlang.org/docs/tutorials/)
-  * [Programmer's Guide](https://www.dartlang.org/docs/)
-  * [Samples](https://www.dartlang.org/samples/)
-  * [A Tour of the Dart Libraries](https://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html)
+  * [Get started](https://www.dartlang.org/guides/get-started)
+  * [Language tour](https://www.dartlang.org/guides/language/language-tour)
+  * [Library tour](https://www.dartlang.org/guides/libraries/library-tour)
+  * [Sample code](https://www.dartlang.org/samples)
   
-This API reference is automatically generated from the source code in the
-[Dart project](https://github.com/dart-lang/sdk). If you'd like to contribute to
-this documentation, see
+This API reference is automatically generated from source code in the [Dart
+SDK project](https://github.com/dart-lang/sdk).
+If you'd like to give feedback or edit this documentation, see
 [Contributing](https://github.com/dart-lang/sdk/wiki/Contributing).
diff --git a/sdk/lib/io/io.dart b/sdk/lib/io/io.dart
index ad7e28d1a24..0feb4ba1596 100644
--- a/sdk/lib/io/io.dart
+++ b/sdk/lib/io/io.dart
@@ -3,22 +3,25 @@
 // BSD-style license that can be found in the LICENSE file.
 
 /**
- * File, socket, HTTP, and other I/O support for server applications.
+ * File, socket, HTTP, and other I/O support for non-web applications.
  *
- * The I/O library is used for Dart server applications,
- * which run on a stand-alone Dart VM from the command line.
- * *This library does not work in browser-based applications.*
+ * **Important:** Browser-based applications can't use this library.
+ * Only servers, command-line scripts, and Flutter mobile apps can import
+ * and use dart:io.
  *
  * This library allows you to work with files, directories,
  * sockets, processes, HTTP servers and clients, and more.
+ * Many operations related to input and output are asynchronous
+ * and are handled using [Future]s or [Stream]s, both of which
+ * are defined in the [dart:async
+ * library](../dart-async/dart-async-library.html).
  *
- * To use this library in your code:
+ * To use the dart:io library in your code:
  *
  *     import 'dart:io';
  *
- * *Note:* Many operations related to input and output are asynchronous
- * and are handled using [Future]s or [Stream]s, both of which
- * are defined in the `dart:async` library.
+ * For an introduction to I/O in Dart, see the [dart:io library
+ * tour](https://www.dartlang.org/dart-vm/io-library-tour).
  *
  * ## File, Directory, and Link
  *
@@ -182,14 +185,6 @@
  * (the program blocks waiting for user to type information):
  *
  *      String inputText = stdin.readLineSync();
- *
- * ## Other resources
- *
- * For an introduction to I/O in Dart, see the [dart:io section of the library
- * tour](https://www.dartlang.org/docs/dart-up-and-running/ch03.html#dartio---io-for-command-line-apps).
- *
- * To learn more about I/O in Dart, refer to the [tutorial about writing
- * command-line apps](https://www.dartlang.org/docs/tutorials/cmdline/).
  */
 library dart.io;