diff --git a/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/extensions/ExtensionDocTest.java b/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/extensions/ExtensionDocTest.java
index fcd932af12..0b40c0986a 100644
--- a/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/extensions/ExtensionDocTest.java
+++ b/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/extensions/ExtensionDocTest.java
@@ -9,16 +9,14 @@ import akka.actor.typed.Behavior;
 import akka.actor.typed.Extension;
 import akka.actor.typed.ExtensionId;
 import akka.actor.typed.javadsl.Behaviors;
-import com.typesafe.config.ConfigFactory;
 import docs.akka.typed.extensions.DatabasePool;
-import docs.akka.typed.extensions.ExtensionDocSpec;
 
 import java.util.concurrent.CompletionStage;
 
-public class ExtensionDocTest {
+interface ExtensionDocTest {
 
   // #shared-resource
-  public static class ExpensiveDatabaseConnection {
+  public class ExpensiveDatabaseConnection {
     public CompletionStage<Object> executeQuery(String query) {
       throw new RuntimeException("I should do a database query");
     }
@@ -27,10 +25,31 @@ public class ExtensionDocTest {
   // #shared-resource
 
   // #extension
-  public static class DatabaseConnectionPool implements Extension {
+  public class DatabaseConnectionPool implements Extension {
+    // #extension
+    // #extension-id
+    public static class Id extends ExtensionId<DatabaseConnectionPool> {
+
+      private static final Id instance = new Id();
+
+      private Id() {}
+
+      // called once per ActorSystem
+      @Override
+      public DatabaseConnectionPool createExtension(ActorSystem<?> system) {
+        return new DatabaseConnectionPool(system);
+      }
+
+      public static DatabaseConnectionPool get(ActorSystem<?> system) {
+        return instance.apply(system);
+      }
+    }
+    // #extension-id
+    // #extension
+
     private final ExpensiveDatabaseConnection _connection;
 
-    public DatabaseConnectionPool(ActorSystem<?> system) {
+    private DatabaseConnectionPool(ActorSystem<?> system) {
       // database configuration can be loaded from config
       // from the actor system
       _connection = new ExpensiveDatabaseConnection();
@@ -42,25 +61,6 @@ public class ExtensionDocTest {
   }
   // #extension
 
-  // #extension-id
-  public static class DatabaseConnectionPoolId extends ExtensionId<DatabaseConnectionPool> {
-
-    private static final DatabaseConnectionPoolId instance = new DatabaseConnectionPoolId();
-
-    private DatabaseConnectionPoolId() {}
-
-    // called once per ActorSystem
-    @Override
-    public DatabaseConnectionPool createExtension(ActorSystem system) {
-      return new DatabaseConnectionPool(system);
-    }
-
-    public static DatabaseConnectionPool get(ActorSystem<?> system) {
-      return instance.apply(system);
-    }
-  }
-  // #extension-id
-
   public static Behavior<Object> initialBehavior() {
     return null;
   }
@@ -69,7 +69,7 @@ public class ExtensionDocTest {
     // #usage
     Behaviors.setup(
         (context) -> {
-          DatabaseConnectionPoolId.get(context.getSystem())
+          DatabaseConnectionPool.Id.get(context.getSystem())
               .connection()
               .executeQuery("insert into...");
           return initialBehavior();
diff --git a/akka-docs/src/main/paradox/typed/extending.md b/akka-docs/src/main/paradox/typed/extending.md
index 7d8d77ab68..1e517502dd 100644
--- a/akka-docs/src/main/paradox/typed/extending.md
+++ b/akka-docs/src/main/paradox/typed/extending.md
@@ -35,10 +35,10 @@ Scala
 Java
 :  @@snip [ExtensionDocTest.java](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/extensions/ExtensionDocTest.java) { #extension }
 
-This is the public API of your extension. Internally in this example we instantiate our expensive database connection.
-The `DatabaseConnectionPool` can be looked up this way any number of times and it will return the same instance. 
+This is the public API of your extension. Internally in this example we instantiate our expensive database connection. 
 
 Then create an @apidoc[akka.actor.typed.ExtensionId] to identify the extension.
+@scala[A good convention is to let the companion object of the `Extension` be the `ExtensionId`.]@java[A good convention is to define the `ExtensionId` as a static inner class of the `Extension`.]
 
 Scala
 :  @@snip [ExtensionDocSpec.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/extensions/ExtensionDocSpec.scala) { #extension-id }
@@ -54,6 +54,8 @@ Scala
 Java
 :  @@snip [ExtensionDocTest.java](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/extensions/ExtensionDocTest.java) { #usage  }
 
+The `DatabaseConnectionPool` can be looked up in this way any number of times and it will return the same instance.
+
 <a id="loading"></a>
 ## Loading from configuration
 
@@ -66,7 +68,7 @@ Scala
 Java
 :   ```ruby
    akka.actor.typed {
-     extensions = ["jdocs.akka.extensions.ExtensionDocTest$DatabaseConnectionPoolId"]
+     extensions = ["jdocs.akka.extensions.ExtensionDocTest$DatabaseConnectionPool$Id"]
    }
    ```