Fix levels and include basic content for API and howto

initializr-docs/src/main/asciidoc/api-guide.adoc

@@ -0,0 +1,6 @@
+[[api-guide]]
+= API Guide
+
+include::metadata-format.adoc[leveloffset=+1]
+
+include::using-the-stubs.adoc[leveloffset=+1]

initializr-docs/src/main/asciidoc/configuration-guide.adoc

@@ -12,16 +12,16 @@ consistent with the chosen Spring Boot generation.
 
 [[create-instance]]
 == Creating your own instance
-Spring Initializr is split in three main modules:
+Spring Initializr is split across three main modules:
 
 * `initializr-generator`: standalone project generation library that can be reused in
 many environments (including embedded in your own project)
-* `initializr-web`: REST endpoints and web interface
+* `initializr-web`: API endpoints and web interface
 * `initializr-actuator`: optional module to provide statistics and metrics on project
 generation
 
 Because it contains several auto-configurations, creating your own instance is quite easy,
-actually you could get started using Spring Initializr itself!
+actually you could get started using Spring Initializr itself to generate a starting point!
 
 Create a new project with the `web` dependency and add the following dependency:
 
@@ -323,6 +323,18 @@ Weight + keywords
 This section provides answers to some common '`how do I do that...`' type of questions
 that often arise when configuring Spring Initializr.
 
+[[howto-add-a-new-checkbox]]
+=== Add a new dependency checkbox
+
+[[howto-override-a-version]]
+=== Override the version of a dependency
+
+[[howto-link-boot-version]]
+=== Link a Boot version to a version of your dependency
+
+[[howto-add-snapshot-repository]]
+=== Configure a snapshot repository
+
 [[howto-dependency-starter-flag]]
 === Make sure a regular dependency brings the base starter
 
@@ -368,7 +380,8 @@ compile("org.ehcache:ehcache")
 ----
 
 You'll notice that the log entry is much more rare. If you do not want to use JSR-107, you
-should configure the cache yourselves:
+should configure the cache yourselves. Here are the caches used by the application (each
+one will require some configuration to get it working):
 
 .Cache configuration
 |===

initializr-docs/src/main/asciidoc/documentation-overview.adoc

@@ -8,33 +8,36 @@ of it as map for the rest of the document. Some sections are targeted to a speci
 audience so this reference guide is not meant to be read in a linear fashion.
 --
 
-Spring Initializr provides an extensible API to generate quickstart projects. Such an API
-can be used standalone or embedded in other tools. We also provide a configurable service:
-you can see our default instance at https://start.spring.io. It provides a simple web UI
-to configure the project to generate and endpoints that you can use via plain HTTP.
+Spring Initializr provides a simple web UI to configure the project to generate and
+endpoints that you can use via plain HTTP: you can see our default instance at
+https://start.spring.io.  The service allows you to customize the project to generate: the
+build system and its coordinates, the language and version, the packaging and finally the
+dependencies to add to the project. The latter is a core concept: based on the chosen
+Spring Boot version, a set of dependencies can be chosen, usually Spring Boot starters,
+that will have a concrete impact on your application. More details in the
+<<user-guide.adoc#user-guide>> section.
 
-The service allows you to customize the project to generate: the build system and its
-coordinates, the language and version, the packaging and finally the dependencies to add
-the project. The latter is a core concept: based on the chosen Spring Boot version, a set
-of dependencies can be chosen, usually Spring Boot starters, that will have a concrete
-impact on your application. More details in the <<user-guide.adoc#user-guide>>.
-
-You can easily create your own instance: there is minimal code involved and the service
-has a very rich configuration structure, allowing you to define not only the values of
-various project attributes but also the list of dependencies and the constraints to apply
-to them.
-
-Spring Initializr also exposes an endpoint that serves its metadata in a well-known format
-to allow third-party clients to provide the necessary assistance. Currently, all the major
-Java IDEs are covered and you can generate a project right from your favourite IDE.
+You can easily create your own instance of the Initializr, by using the jars as libraries
+in your own app. There is minimal code involved and the service has a very rich
+configuration structure, allowing you to define not only the values of various project
+attributes but also the list of dependencies and the constraints to apply to them. If that
+sounds interesting, then the <<configuration-guide.adoc#configuration-guide>> section has
+all the details you need. You might only want to modify an existing instance of the
+Initializr, e.g. to add a new dependency type, or update the version of an existing
+one. For those and other simple and common use cases check out the
+<<configuration-guide.adoc#configuration-howto>> section.
 
+The Initializr also provides an extensible API to generate quickstart projects, and to
+inspect the metadata used to generate projects, for instance to list the available
+dependencies and versions. The API can be used standalone or embedded in other tools
+(e.g. it is used in Spring Tool Suite, and in the IntelliJ and Netbeans plugins for Spring
+Boot). These features are covered in a separate <<api-guide.adoc#api-guide>> section of
+this document.
 
 [[initializr-documentation-about]]
 == About the documentation
 The Spring Initializr reference guide is available as
-{spring-initializr-docs}/html[html],
-{spring-initializr-docs}/pdf/spring-boot-reference.pdf[pdf]
-and {spring-initializr-docs}/epub/spring-boot-reference.epub[epub] documents. The
+{spring-initializr-docs}/html[html]. The
 latest copy is available at {spring-initializr-docs-current}.
 
 Copies of this document may be made for your own use and for

initializr-docs/src/main/asciidoc/index.adoc

@@ -23,7 +23,8 @@ Stéphane Nicoll; Dave Syer
 
 // ======================================================================================
 
-include::documentation-overview.adoc[]
-include::user-guide.adoc[]
-include::configuration-guide.adoc[]
+include::documentation-overview.adoc[leveloffset=+1]
+include::user-guide.adoc[leveloffset=+1]
+include::configuration-guide.adoc[leveloffset=+1]
+include::api-guide.adoc[leveloffset=+1]
 // ======================================================================================