Add notes to docs about new annotation model

- Relates #637

Author: jvalkeal

spring-shell-docs/src/main/asciidoc/using-shell-basics-reading.adoc

@@ -0,0 +1,18 @@
+[[using-shell-basics-reading]]
+=== Reading Docs
+
+Throughout this documentation, we make references to configuring something by using
+annotations or programmatic examples.
+
+NOTE: There are two annotation models, <<commands-registration-annotation, annotations>>
+referred to new annotation model, <<commands-registration-legacyannotation, legacy annotations>>
+referred to old legacy annotation model.
+
+Old legacy annotation model mostly relates to use of `@ShellMethod` and `@ShellOption` and
+new annotation model relates to use of `@Command`.
+
+The programmatic model is how things are actually registered, even if you use annotations.
+
+NOTE: Currently whole documentation structure is in transit to provide better
+structure how things can be used using different ways to provide configurations.
+So pardon a for little confusion now and there during a transit.

spring-shell-docs/src/main/asciidoc/using-shell-basics.adoc

@@ -13,16 +13,4 @@ Essentially, a few things needs to happen before you have a working Spring Shell
 You can get a full working Spring Shell application without defining any user-level commands
 as some basic built-in commands (such as `help` and `history`) are provided.
 
-[NOTE]
-====
-Throughout this documentation, we make references to configuring something by using
-annotations (mostly relates to use of `@ShellMethod` and `@ShellOption`) and to the
-programmatic way (which uses `CommandRegistration`).
-
-The programmatic model is how things are actually registered, even if you use annotations.
-The `@ShellMethod` and `@ShellOption` annotations are a legacy feature
-that we do not yet want to remove. `CommandRegistration` is the new development
-model where new features are added. We are most likely going to replace existing
-annotations with something better, to support new features in a
-`CommandRegistration` model.
-====
+include::using-shell-basics-reading.adoc[]

spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc

@@ -16,6 +16,6 @@ part without breaking existing applications.
 
 include::using-shell-commands-registration-annotation.adoc[]
 
-include::using-shell-commands-registration-legacyannotation.adoc[]
-
 include::using-shell-commands-registration-programmatic.adoc[]
+
+include::using-shell-commands-registration-legacyannotation.adoc[]