diff --git a/examples/api/README.md b/examples/api/README.md
index 07574a2b30..6e670b7835 100644
--- a/examples/api/README.md
+++ b/examples/api/README.md
@@ -77,8 +77,14 @@ Use `{@tool dartpad}` for Dartpad examples, and use `{@tool sample}` for
 examples that shouldn't be run/shown in Dartpad.
 
 Once that comment block is inserted in the source code, create a new file at the
-appropriate path under [`examples/api`](.). You should also add tests for your
-sample code under [`examples/api/test`](./test).
+appropriate path under [`examples/api`](.) that matches the location of the
+source file they are linked from, and are named for the symbol they are attached
+to, in lower_snake_case, with an index relating to their order within the doc
+comment. So, for the `Curve2D` case, since it's in the `animation` package, in
+a file called `curves.dart`, and it's the first example, it goes in
+`examples/api/lib/animation/curves/curve2_d.0.dart`.
+
+You should also add tests for your sample code under [`examples/api/test`](./test).
 
 The entire example should be in a single file, so that Dartpad can load it.
 
@@ -131,5 +137,5 @@ Tests go into a directory under [test](./test) that matches their location under
 `_test.dart` at the end, like other tests. For instance, a `LayoutBuilder`
 example that resides in [`lib/widgets/layout_builder/layout_builder.0.dart`](
 ./lib/widgets/layout_builder/layout_builder.0.dart) would have its tests in a
-file named [`test/animation/curves/curve2_d.0_test.dart`](
+file named [`test/widgets/layout_builder/layout_builder.0_test.dart`](
 ./test/widgets/layout_builder/layout_builder.0_test.dart)