diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc
index 14d8c9e2..0d6d0a59 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc
@@ -1,4 +1,4 @@
-=== Annotation Model
+==== Annotation Model
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 When you use the standard API, methods on beans are turned into executable commands, provided that:
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-programmaticmodel.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-programmaticmodel.adoc
index 60ef8ac8..625693d4 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-programmaticmodel.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-programmaticmodel.adoc
@@ -1,4 +1,4 @@
-=== Programmatic Model
+==== Programmatic Model
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 In the programmatic model, `CommandRegistration` is defined as a `@Bean`, and it is automatically registered:
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc
new file mode 100644
index 00000000..5fa4cec5
--- /dev/null
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc
@@ -0,0 +1,12 @@
+=== Registration
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+There are two different ways to define a command: through an annotation model and
+through a programmatic model. In the annotation model, you define your methods
+in a class and annotate the class and the methods with specific annotations.
+In the programmatic model, you use a more low level approach, defining command
+registrations (either as beans or by dynamically registering with a command catalog).
+
+include::using-shell-commands-annotationmodel.adoc[]
+
+include::using-shell-commands-programmaticmodel.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc
index 48518f7f..50c319e1 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc
@@ -5,15 +5,7 @@ In this section, we go through an actual command registration and leave command
 and execution for later in a documentation. You can find more detailed info in
 <<appendix-tech-intro-registration>>.
 
-There are two different ways to define a command: through an annotation model and
-through a programmatic model. In the annotation model, you define your methods
-in a class and annotate the class and the methods with specific annotations. In the programmatic model,
-you use a more low level approach, defining command registrations (either
-as beans or by dynamically registering with a command catalog).
-
-include::using-shell-commands-annotationmodel.adoc[]
-
-include::using-shell-commands-programmaticmodel.adoc[]
+include::using-shell-commands-registration.adoc[]
 
 include::using-shell-commands-organize.adoc[]