diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-native.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-building.adoc
similarity index 93%
rename from spring-shell-docs/src/main/asciidoc/using-shell-native.adoc
rename to spring-shell-docs/src/main/asciidoc/using-shell-building.adoc
index a74d2b3b..8e1e58c0 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-native.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-building.adoc
@@ -1,5 +1,8 @@
+[[using-shell-building]]
+=== Building
+
 [[native]]
-=== Native Support
+==== Native Support
 
 Re-work with _2.1.x_ brings in an experimental support for compiling shell application
 into _native_ application with _GraalVM_ and _spring-native_. As underlying _jline_
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-define-command.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc
similarity index 71%
rename from spring-shell-docs/src/main/asciidoc/using-shell-define-command.adoc
rename to spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc
index cd22975a..19ea7138 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-define-command.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc
@@ -1,17 +1,6 @@
-=== Define a Command
+==== Annotation Model
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
-In this section we go through an actual command registration and leave command options
-and execution later in a documentation. More detailed info can be found from
-<<appendix-tech-intro-registration>>.
-
-There are two different ways to define a command. Firstly through an annotation model and
-secondly through programmatic model. Annotation model if where you define your methods
-in a class and annotate class and methods with a spesific annotations. Programmatic model
-is where things are done on a more low level ways by defining command registrations either
-as beans or registering those with a command catalog dynamically.
-
-==== Annotation Model
 When you use the standard API, methods on beans are turned into executable commands, provided that:
 
 * The bean class bears the `@ShellComponent` annotation. This is used to restrict the set of beans
@@ -68,13 +57,3 @@ The command key can contain pretty much any character, including spaces. When co
 keep in mind that consistency is often appreciated by users (that is, you should avoid mixing dashed-names with
 spaced names and other inconsistencies).
 ====
-
-==== Programmatic Model
-`CommandRegistration` can be defined as a `@Bean` and it's automatically registered.
-
-====
-[source, java, indent=0]
-----
-include::{snippets}/CommandRegistrationBeanSnippets.java[tag=snippet1]
-----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-availability.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc
similarity index 99%
rename from spring-shell-docs/src/main/asciidoc/using-shell-availability.adoc
rename to spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc
index 1eeedc9c..067b3590 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-availability.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc
@@ -1,5 +1,5 @@
 [[dynamic-command-availability]]
-=== Dynamic Command Availability
+==== Dynamic Command Availability
 
 Registered commands do not always make sense, due to the internal state of the application.
 For example, there may be a `download` command, but it only works once the user has used `connect` on a remote
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-organize.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-organize.adoc
similarity index 98%
rename from spring-shell-docs/src/main/asciidoc/using-shell-organize.adoc
rename to spring-shell-docs/src/main/asciidoc/using-shell-commands-organize.adoc
index 100eec47..2aec4748 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-organize.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-organize.adoc
@@ -1,5 +1,5 @@
 [[organizing-commands]]
-=== Organizing Commands
+==== Organizing Commands
 
 When your shell starts to provide a lot of functionality, you may end up
 with a lot of commands, which could be confusing for your users. By typing `help`,
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
new file mode 100644
index 00000000..0e263d20
--- /dev/null
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-programmaticmodel.adoc
@@ -0,0 +1,11 @@
+==== Programmatic Model
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+`CommandRegistration` can be defined as a `@Bean` and it's automatically registered.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationBeanSnippets.java[tag=snippet1]
+----
+====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc
new file mode 100644
index 00000000..59e9fc10
--- /dev/null
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc
@@ -0,0 +1,20 @@
+=== Commands
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+In this section we go through an actual command registration and leave command options
+and execution later in a documentation. More detailed info can be found from
+<<appendix-tech-intro-registration>>.
+
+There are two different ways to define a command. Firstly through an annotation model and
+secondly through programmatic model. Annotation model if where you define your methods
+in a class and annotate class and methods with a spesific annotations. Programmatic model
+is where things are done on a more low level ways by defining command registrations either
+as beans or registering those with a command catalog dynamically.
+
+include::using-shell-commands-annotationmodel.adoc[]
+
+include::using-shell-commands-programmaticmodel.adoc[]
+
+include::using-shell-commands-organize.adoc[]
+
+include::using-shell-commands-availability.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-built-in.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin.adoc
similarity index 97%
rename from spring-shell-docs/src/main/asciidoc/using-shell-built-in.adoc
rename to spring-shell-docs/src/main/asciidoc/using-shell-components-builtin.adoc
index 244f9675..57b286e8 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-built-in.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin.adoc
@@ -1,5 +1,5 @@
 [[built-in-commands]]
-=== Built-In Commands
+==== Built-In Commands
 
 Any application built by using the `{starter-artifactId}` artifact
 (or, to be more precise, the `spring-shell-standard-commands` dependency) comes with a set of built-in commands.
@@ -7,7 +7,7 @@ You can override or disable these commands individually (see <<overriding-or-dis
 However, if they are not overridden or disabled, this section describes their behavior.
 
 [[help-command]]
-==== Help
+===== Help
 
 Running a shell application often implies that the user is in a graphically limited
 environment. Also, while we are nearly always connected in the era of mobile phones,
@@ -62,17 +62,17 @@ OPTIONS
 ----
 ====
 
-==== Clear
+===== Clear
 The `clear` command does what you would expect and clears the screen, resetting the prompt
 in the top left corner.
 
-==== Exit
+===== Exit
 
 The `quit` command (also aliased as `exit`) requests the shell to quit, gracefully
 closing the Spring application context. If not overridden, a JLine `History` bean writes a history of all
 commands to disk, so that they are available again (see <<interacting-with-the-shell>>) on the next launch.
 
-==== Stacktrace
+===== Stacktrace
 
 When an exception occurs inside command code, it is caught by the shell and a simple, one-line message is displayed
 so as not to overflow the user with too much information.
@@ -82,18 +82,18 @@ To this end, Spring Shell remembers the last exception that occurred, and the us
 command to print all the details on the console.
 
 [[script-command]]
-==== Script
+===== Script
 
 The `script` command accepts a local file as an argument and replays commands found there, one at a time.
 
 Reading from the file behaves exactly like inside the interactive shell, so lines starting with `//` are considered
 to be comments and are ignored, while lines ending with `\` trigger line continuation.
 
-==== History
+===== History
 
 The `history` command shows history of a commands which has been executed.
 
-==== Completion
+===== Completion
 
 The `completion` command set allows you to create _scripts_ files which can be used
 with am OS shell implementations to provide completion. This is very usefull when
@@ -101,7 +101,7 @@ working with non-interactive mode.
 
 Currently only implementation is for _bash_ which works with `bash` sub-command.
 
-==== Version
+===== Version
 
 The `version` command shows existing _build_ and _git_ info by integrating into
 Boot's `BuildProperties` and `GitProperties` if those exists in a shell app.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-ui-components.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc
similarity index 97%
rename from spring-shell-docs/src/main/asciidoc/using-shell-ui-components.adoc
rename to spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc
index 7454f77f..5317a5c5 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-ui-components.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc
@@ -1,5 +1,5 @@
 [[uicomponents]]
-=== UI Components
+==== UI Components
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Starting from _2.1.x_ there is a new component model which provides
@@ -18,7 +18,7 @@ Build-in components generally follow logic:
 * Exit
 * Render final status of a component state
 
-==== Component Render
+===== Component Render
 
 There are two ways to implement component rendering, firstly fully
 programmatically or secondly using a _ANTLR Stringtemplate_. Though
@@ -109,9 +109,9 @@ from a parent component types, those context variables are shown below.
 |===
 
 
-==== Build-in Components
+===== Build-in Components
 
-===== String Input
+====== String Input
 
 Used to ask a simple text input from a user, optionally masking values
 if content contains something sensitive.
@@ -152,7 +152,7 @@ Context object is `StringInputContext`.
 |Parent context variables <<textcomponentcontext-template-variables>>
 |===
 
-===== Path Input
+====== Path Input
 
 Used to ask a `Path` from a user and gives additional info about a path itself.
 
@@ -176,7 +176,7 @@ Context object is `PathInputContext`.
 |Parent context variables <<textcomponentcontext-template-variables>>
 |===
 
-===== Confirmation
+====== Confirmation
 
 Used to ask a simple confirmation from a user and essentially is
 yes/no question.
@@ -204,7 +204,7 @@ Context object is `ConfirmationInputContext`.
 |Parent context variables <<textcomponentcontext-template-variables>>
 |===
 
-===== Single Select
+====== Single Select
 
 Used to ask an item from a list and is essentially similar to simple
 dropbox implementation.
@@ -235,7 +235,7 @@ Context object is `SingleItemSelectorContext`.
 |Parent context variables <<selectorcomponentcontext-template-variables>>
 |===
 
-===== Multi Select
+====== Multi Select
 
 Used to ask an items from a list.
 
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components.adoc
new file mode 100644
index 00000000..b524cca8
--- /dev/null
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components.adoc
@@ -0,0 +1,7 @@
+[[using-shell-components]]
+=== Components
+
+include::using-shell-components-ui.adoc[]
+
+include::using-shell-components-builtin.adoc[]
+
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customize.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-customization-generic.adoc
similarity index 96%
rename from spring-shell-docs/src/main/asciidoc/using-shell-customize.adoc
rename to spring-shell-docs/src/main/asciidoc/using-shell-customization-generic.adoc
index 94f0bfa2..92529884 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-customize.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-customization-generic.adoc
@@ -1,7 +1,7 @@
-=== Customizing the Shell
+==== Customizing the Shell
 
 [[overriding-or-disabling-built-in-commands]]
-==== Overriding or Disabling Built-In Commands
+===== Overriding or Disabling Built-In Commands
 
 Spring Shell provides <<built-in-commands,Built-in commands>> to let people achieve everyday tasks that many if not
 all shell applications need. If you are not happy with the way they behave, though, you can disable or override them,
@@ -33,7 +33,7 @@ dependencies, don't include that one in. The follwoing example shows how to excl
 =====
 
 [[disabling-specific-commands]]
-===== Disabling Specific Commands
+====== Disabling Specific Commands
 
 To disable a single built-in command, set the `spring.shell.command.<command>.enabled` property to `false` in the
 application `Environment`. One way to do so is to pass extra arguments to the Boot application in your `main()`
@@ -51,7 +51,7 @@ entry point:
 <1> This disables the integrated `help` command
 ====
 
-===== Overriding Specific Commands
+====== Overriding Specific Commands
 
 If, instead of disabling a command, you would rather provide your own implementation, then you can either:
 
@@ -87,7 +87,7 @@ always welcome!
 
 // TBD
 
-==== PromptProvider
+===== PromptProvider
 After each command invocation, the shell waits for new input from the user, displaying
 a prompt in yellow:
 
@@ -133,7 +133,7 @@ public class CustomPromptProvider implements PromptProvider {
 ----
 ====
 
-==== Customizing Command Line Options Behavior
+===== Customizing Command Line Options Behavior
 
 There can be exactly one shell spesific `ShellApplicationRunner` which simply extends
 Boot's `ApplicationRunner`. Default behariour is to have actual runner logic in
@@ -151,7 +151,7 @@ You can override bean type of `ShellApplicationRunner` if there's a need to
 customise shell running logic.
 ====
 
-==== Customizing Arguments Conversion
+===== Customizing Arguments Conversion
 
 Conversion from text input to actual method arguments uses the standard Spring
 https://docs.spring.io/spring/docs/4.3.11.RELEASE/spring-framework-reference/htmlsingle/#core-convert[conversion] mechanism.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-styling.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-customization-styling.adoc
similarity index 98%
rename from spring-shell-docs/src/main/asciidoc/using-shell-styling.adoc
rename to spring-shell-docs/src/main/asciidoc/using-shell-customization-styling.adoc
index d8810bc7..1d1bb5d3 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-styling.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-customization-styling.adoc
@@ -1,5 +1,5 @@
 [[styling]]
-=== Styling
+==== Styling
 
 Starting with _2.1.x_ there is a support for centrally handling styling and theming.
 There is a default theme named _default_ which can be changed using property
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-customization.adoc
new file mode 100644
index 00000000..48d15073
--- /dev/null
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-customization.adoc
@@ -0,0 +1,6 @@
+[[using-shell-customization]]
+=== Customization
+
+include::using-shell-customization-generic.adoc[]
+
+include::using-shell-customization-styling.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-interaction-mode.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc
similarity index 95%
rename from spring-shell-docs/src/main/asciidoc/using-shell-interaction-mode.adoc
rename to spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc
index 5206ea7f..0e1809ac 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-interaction-mode.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc
@@ -1,4 +1,6 @@
-=== Interaction Mode
+=== Execution
+
+==== Interaction Mode
 
 Starting from _2.1.x_ a build-in support has been added to distinguish between interactive
 and non-interactive modes. This has been added so that it's easier to use shell as a
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-invoke-command.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-generic.adoc
similarity index 97%
rename from spring-shell-docs/src/main/asciidoc/using-shell-invoke-command.adoc
rename to spring-shell-docs/src/main/asciidoc/using-shell-options-generic.adoc
index 2ce0915a..e574408a 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-invoke-command.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-generic.adoc
@@ -1,8 +1,8 @@
-=== Invoking your Commands
+==== Invoking your Commands
 
 This section addresses how you can control the way in which your commands are invoked.
 
-==== By Name Versus Positional Parameters
+===== By Name Versus Positional Parameters
 
 As seen <<documenting-the-command,earlier>>, decorating a method with `@ShellMethod` is the sole requirement for creating a command.
 
@@ -51,7 +51,7 @@ You said a=1, b=2, c=3
 <5> The non by-name parameters are resolved in the order in which they appear.
 ====
 
-===== Customizing the Named Parameter Keys
+====== Customizing the Named Parameter Keys
 
 As seen <<your-first-command,earlier>>, the default strategy for deriving the key for a named parameter is to use the Java
 name of the method signature and prefix it with two dashes (`--`). You can customize this in two ways:
@@ -91,7 +91,7 @@ built-in <<help-command,`help`>> command:
 =====
 
 [[optional-parameters-default-values]]
-==== Optional Parameters and Default Values
+===== Optional Parameters and Default Values
 
 Spring Shell provides the ability to give parameters default values, which lets users omit
 those parameters. Consider the following command definition:
@@ -117,7 +117,7 @@ Hello World
 ----
 ====
 
-==== Parameter Arity
+===== Parameter Arity
 Up to now, it has always been assumed that each parameter maps to a single word entered by the user.
 Situations may arise, though, when a parameter value should be multi-valued. This is driven by the `arity()`
 attribute of the `@ShellOption` annotation. You can use a collection or array for the parameter type and specify how
@@ -157,7 +157,7 @@ shell:>add --numbers 1 --numbers 2 --numbers 3.3
 ====
 =====
 
-===== Varying Amount Arity
+====== Varying Amount Arity
 
 The above example demonstrates requiring a known, constant arity for a parameter, three in this case. Allowing any number of multiple values of a parameter can be achieved by leaving `arity` unspecified and using Spring's built-in comma separated value parsing for collections and/or arrays:
 [source, java]
@@ -182,7 +182,7 @@ shell:>add --numbers 1,2,3.3,4,5
 ----
 ====
 
-===== Special Handling of Boolean Parameters
+====== Special Handling of Boolean Parameters
 
 When it comes to parameter arity, one kind of parameter receives a special treatment by default, as
 is often the case in command-line utilities.
@@ -233,7 +233,7 @@ If you would like to allow this behavior (and forego the flag approach), then fo
 =====
 
 [[quotes-handling]]
-==== Quotes Handling
+===== Quotes Handling
 
 Spring Shell takes user input and tokenizes it into words, splitting on space characters.
 If the user wants to provide a parameter value that contains spaces, that value needs to be quoted.
@@ -307,7 +307,7 @@ You said This is a single value
 ====
 
 [[interacting-with-the-shell]]
-==== Interacting with the Shell
+===== Interacting with the Shell
 
 The Spring Shell project builds on top of the https://github.com/jline/jline3[JLine] library and, as a result, brings
 a lot of nice interactive features, some of which are detailed in this section.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-validate-command.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-validation.adoc
similarity index 96%
rename from spring-shell-docs/src/main/asciidoc/using-shell-validate-command.adoc
rename to spring-shell-docs/src/main/asciidoc/using-shell-options-validation.adoc
index c33c99b5..08a25707 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-validate-command.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-validation.adoc
@@ -1,5 +1,5 @@
 [[validating-command-arguments]]
-=== Validating Command Arguments
+==== Validating Command Arguments
 
 Spring Shell integrates with the https://beanvalidation.org/[Bean Validation API] to support
 automatic and self-documenting constraints on command parameters.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc
new file mode 100644
index 00000000..f6008783
--- /dev/null
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc
@@ -0,0 +1,6 @@
+[[using-shell-options]]
+=== Options
+
+include::using-shell-options-generic.adoc[]
+
+include::using-shell-options-validation.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell.adoc b/spring-shell-docs/src/main/asciidoc/using-shell.adoc
index c9e3fbe9..10c95afd 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell.adoc
@@ -12,24 +12,14 @@ us to clean up codebase and make some needed breaking changes.
 
 include::using-shell-basics.adoc[]
 
-include::using-shell-define-command.adoc[]
+include::using-shell-commands.adoc[]
 
-include::using-shell-invoke-command.adoc[]
+include::using-shell-options.adoc[]
 
-include::using-shell-validate-command.adoc[]
+include::using-shell-building.adoc[]
 
-include::using-shell-availability.adoc[]
+include::using-shell-components.adoc[]
 
-include::using-shell-organize.adoc[]
+include::using-shell-customization.adoc[]
 
-include::using-shell-built-in.adoc[]
-
-include::using-shell-interaction-mode.adoc[]
-
-include::using-shell-native.adoc[]
-
-include::using-shell-styling.adoc[]
-
-include::using-shell-ui-components.adoc[]
-
-include::using-shell-customize.adoc[]
+include::using-shell-execution.adoc[]