diff --git a/core/modules/simpletest/src/BrowserTestBase.php b/core/modules/simpletest/src/BrowserTestBase.php
index 57caa51..218d03d 100644
--- a/core/modules/simpletest/src/BrowserTestBase.php
+++ b/core/modules/simpletest/src/BrowserTestBase.php
@@ -31,9 +31,18 @@
 /**
  * Test case for functional Drupal tests.
  *
- * Currently, this class should only be used for JavaScript testing. For
- * everything else, WebTestBase is better for now. This is likely to change
- * after Drupal 8.0.
+ * Currently, this class should only be used for contrib module testing. Note
+ * that it does not have feature parity with WebTestBase and is notably missing
+ * the following features:
+ *
+ * - verbose output - see https://www.drupal.org/node/2469721
+ * - ajax form emulation - see https://www.drupal.org/node/2469713
+ *
+ * Use of this module for tests in core is postponed until 8.1.x.
+ *
+ * Tests extending BrowserTestBase must exist in the
+ * Drupal\Tests\yourmodule\Functional namespace and live in the
+ * modules/yourmodule/Tests/Functional directory.
  *
  * @ingroup testing
  *