Avoid trivialising what the reader's learning about

Closes gh-22408

Author: wilkinsona

CONTRIBUTING.adoc

@@ -1,7 +1,7 @@
 = Contributing to Spring Boot
 
 Spring Boot is released under the Apache 2.0 license. If you would like to contribute
-something, or simply want to hack on the code this document should help you get started.
+something, or want to hack on the code this document should help you get started.
 
 
 
@@ -55,7 +55,7 @@ added after the original pull request but before a merge.
   `./mvnw io.spring.javaformat:spring-javaformat-maven-plugin:apply`.
 * The build includes checkstyle rules for many of our code conventions. Run
   `./mvnw validate` if you want to check you changes are compliant.
-* Make sure all new `.java` files to have a simple Javadoc class comment with at least an
+* Make sure all new `.java` files have a Javadoc class comment with at least an
   `@author` tag identifying you, and preferably at least a paragraph on what the class is
   for.
 * Add the ASF license header comment to all new `.java` files (copy from existing files

README.adoc

@@ -1,7 +1,7 @@
 = Spring Boot image:https://ci.spring.io/api/v1/teams/spring-boot/pipelines/spring-boot-2.1.x/jobs/build/badge["Build Status", link="https://ci.spring.io/teams/spring-boot/pipelines/spring-boot-2.1.x?groups=Build"] image:https://badges.gitter.im/Join Chat.svg["Chat",link="https://gitter.im/spring-projects/spring-boot?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]
 :docs: https://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference
 
-Spring Boot makes it easy to create Spring-powered, production-grade applications and
+Spring Boot helps you to create Spring-powered, production-grade applications and
 services with absolute minimum fuss. It takes an opinionated view of the Spring platform
 so that new and existing users can quickly get to the bits they need.
 
@@ -163,7 +163,7 @@ There are a number of modules in Spring Boot, here is a quick overview:
 The main library providing features that support the other parts of Spring Boot,
 these include:
 
-* The `SpringApplication` class, providing static convenience methods that make it easy
+* The `SpringApplication` class, providing static convenience methods that can be used
 to write a stand-alone Spring Application. Its sole job is to create and refresh an
 appropriate Spring `ApplicationContext`
 * Embedded web applications with a choice of container (Tomcat, Jetty or Undertow)
@@ -190,14 +190,14 @@ Starters are a set of convenient dependency descriptors that you can include in
 your application. You get a one-stop-shop for all the Spring and related technology
 that you need without having to hunt through sample code and copy paste loads of
 dependency descriptors. For example, if you want to get started using Spring and JPA for
-database access just include the `spring-boot-starter-data-jpa` dependency in your
+database access include the `spring-boot-starter-data-jpa` dependency in your
 project, and you are good to go.
 
 
 
 === spring-boot-cli
-The Spring command line application compiles and runs Groovy source, making it super
-easy to write the absolute minimum of code to get an application running. Spring CLI
+The Spring command line application compiles and runs Groovy source, allowing you to
+write the absolute minimum of code to get an application running. Spring CLI
 can also watch files, automatically recompiling and restarting when they change.
 
 
@@ -261,7 +261,7 @@ The https://spring.io/[spring.io] site contains several guides that show how to
 Boot step-by-step:
 
 * https://spring.io/guides/gs/spring-boot/[Building an Application with Spring Boot] is a
-  very basic guide that shows you how to create a simple application, run it and add some
+  very basic guide that shows you how to create an application, run it and add some
   management services.
 * https://spring.io/guides/gs/actuator-service/[Building a RESTful Web Service with Spring
   Boot Actuator] is a guide to creating a REST web service and also shows how the server

spring-boot-project/spring-boot-actuator/README.adoc

@@ -8,7 +8,7 @@ https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#production
 covers the features in more detail.
 
 == Enabling the Actuator
-The simplest way to enable the features is to add a dependency to the
+The recommended way to enable the features is to add a dependency to the
 `spring-boot-starter-actuator` '`Starter`'. To add the actuator to a Maven-based project,
 add the following '`Starter`' dependency:
 

spring-boot-project/spring-boot-docs/src/main/asciidoc/appendix-configuration-metadata.adoc

@@ -12,7 +12,7 @@ However, it is possible to <<configuration-metadata-additional-metadata,write pa
 [[configuration-metadata-format]]
 === Metadata Format
 Configuration metadata files are located inside jars under `META-INF/spring-configuration-metadata.json`.
-They use a simple JSON format with items categorized under either "`groups`" or "`properties`" and additional values hints categorized under "hints", as shown in the following example:
+They use a JSON format with items categorized under either "`groups`" or "`properties`" and additional values hints categorized under "hints", as shown in the following example:
 
 [source,json,indent=0]
 ----
@@ -736,7 +736,7 @@ This dependency ensures that the additional metadata is available when the annot
 The processor picks up both classes and methods that are annotated with `@ConfigurationProperties`.
 The Javadoc for field values within configuration classes is used to populate the `description` attribute.
 
-NOTE: You should only use simple text with `@ConfigurationProperties` field Javadoc, since they are not processed before being added to the JSON.
+NOTE: You should only use plain text with `@ConfigurationProperties` field Javadoc, since they are not processed before being added to the JSON.
 
 Properties are discovered through the presence of standard getters and setters with special handling for collection types (that is detected even if only a getter is present).
 The annotation processor also supports the use of the `@Data`, `@Getter`, and `@Setter` lombok annotations.

spring-boot-project/spring-boot-docs/src/main/asciidoc/deployment.adoc

@@ -26,7 +26,7 @@ It minimizes divergence between development and production environments.
 
 Ideally, your application, like a Spring Boot executable jar, has everything that it needs to run packaged within it.
 
-In this section, we look at what it takes to get the <<getting-started.adoc#getting-started-first-application, simple application that we developed>> in the "`Getting Started`" section up and running in the Cloud.
+In this section, we look at what it takes to get the <<getting-started.adoc#getting-started-first-application, application that we developed>> in the "`Getting Started`" section up and running in the Cloud.
 
 
 
@@ -227,7 +227,7 @@ The options include:
 * AWS Container Registry
 
 Each has different features and pricing models.
-In this document, we describe only the simplest option: AWS Elastic Beanstalk.
+In this document, we describe to approach using AWS Elastic Beanstalk.
 
 
 
@@ -399,7 +399,7 @@ Then deploy with `mvn appengine:deploy` (if you need to authenticate first, the
 == Installing Spring Boot Applications
 In addition to running Spring Boot applications by using `java -jar`, it is also possible to make fully executable applications for Unix systems.
 A fully executable jar can be executed like any other executable binary or it can be <<deployment-service,registered with `init.d` or `systemd`>>.
-This makes it very easy to install and manage Spring Boot applications in common production environments.
+This helps when installing and managing Spring Boot applications in common production environments.
 
 CAUTION: Fully executable jars work by embedding an extra script at the front of the file.
 Currently, some tools do not accept this format, so you may not always be able to use this technique.
@@ -740,7 +740,7 @@ The following environment properties are supported with the default script:
 | The explicit location of the jar file, in case the script is being used to launch a jar that it is not actually embedded.
 
 | `DEBUG`
-| If not empty, sets the `-x` flag on the shell process, making it easy to see the logic in the script.
+| If not empty, sets the `-x` flag on the shell process, allowing you to see the logic in the script.
 
 | `STOP_WAIT_TIME`
 | The time in seconds to wait when stopping the application before forcing a shutdown (`60` by default).

spring-boot-project/spring-boot-docs/src/main/asciidoc/getting-started.adoc

@@ -13,7 +13,7 @@ We then walk you through building your first Spring Boot application, discussing
 
 [[getting-started-introducing-spring-boot]]
 == Introducing Spring Boot
-Spring Boot makes it easy to create stand-alone, production-grade Spring-based Applications that you can run.
+Spring Boot helps you to create stand-alone, production-grade Spring-based Applications that you can run.
 We take an opinionated view of the Spring platform and third-party libraries, so that you can get started with minimum fuss.
 Most Spring Boot applications need very little Spring configuration.
 
@@ -252,7 +252,7 @@ Get SDKMAN! from https://sdkman.io and install Spring Boot by using the followin
 	Spring Boot v{spring-boot-version}
 ----
 
-If you develop features for the CLI and want easy access to the version you built, use the following commands:
+If you develop features for the CLI and want access to the version you built, use the following commands:
 
 [indent=0,subs="verbatim,quotes,attributes"]
 ----
@@ -416,7 +416,7 @@ If you manually installed the CLI, follow the <<getting-started-manual-cli-insta
 
 [[getting-started-first-application]]
 == Developing Your First Spring Boot Application
-This section describes how to develop a simple "`Hello World!`" web application that highlights some of Spring Boot's key features.
+This section describes how to develop a small "`Hello World!`" web application that highlights some of Spring Boot's key features.
 We use Maven to build this project, since most IDEs support it.
 
 [TIP]
@@ -626,7 +626,7 @@ Spring Boot still does its best to auto-configure your application.
 [[getting-started-first-application-main-method]]
 ==== The "`main`" Method
 The final part of our application is the `main` method.
-This is just a standard method that follows the Java convention for an application entry point.
+This is a standard method that follows the Java convention for an application entry point.
 Our main method delegates to Spring Boot's `SpringApplication` class by calling `run`.
 `SpringApplication` bootstraps our application, starting Spring, which, in turn, starts the auto-configured Tomcat web server.
 We need to pass `Example.class` as an argument to the `run` method to tell `SpringApplication` which is the primary Spring component.

spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc

@@ -40,7 +40,7 @@ The following example registers `ProjectConstraintViolationFailureAnalyzer`:
 	com.example.ProjectConstraintViolationFailureAnalyzer
 ----
 
-NOTE: If you need access to the `BeanFactory` or the `Environment`, your `FailureAnalyzer` can simply implement `BeanFactoryAware` or `EnvironmentAware` respectively.
+NOTE: If you need access to the `BeanFactory` or the `Environment`, your `FailureAnalyzer` can implement `BeanFactoryAware` or `EnvironmentAware` respectively.
 
 
 
@@ -417,7 +417,7 @@ Many Spring Boot starters include default embedded containers.
 * For reactive stack applications, the `spring-boot-starter-webflux` includes  Reactor Netty by including `spring-boot-starter-reactor-netty`, but you can use `spring-boot-starter-tomcat`, `spring-boot-starter-jetty`, or `spring-boot-starter-undertow` instead.
 
 When switching to a different HTTP server, you need to exclude the default dependencies in addition to including the one you need.
-Spring Boot provides separate starters for HTTP servers to help make this process as easy as possible.
+To help with this process, Spring Boot provides a separate starter for each of the supported HTTP servers.
 
 The following Maven example shows how to exclude Tomcat and include Jetty for Spring MVC:
 
@@ -1020,7 +1020,7 @@ The `ObjectMapper` (or `XmlMapper` for Jackson XML converter) instance (created
 Spring Boot also has some features to make it easier to customize this behavior.
 
 You can configure the `ObjectMapper` and `XmlMapper` instances by using the environment.
-Jackson provides an extensive suite of simple on/off features that can be used to configure various aspects of its processing.
+Jackson provides an extensive suite of on/off features that can be used to configure various aspects of its processing.
 These features are described in six enums (in Jackson) that map onto properties in the environment:
 
 |===
@@ -1281,7 +1281,7 @@ This ensures efficient sharing of resources for the server receiving requests an
 == Logging
 Spring Boot has no mandatory logging dependency, except for the Commons Logging API, which is typically provided by Spring Framework's `spring-jcl` module.
 To use https://logback.qos.ch[Logback], you need to include it and `spring-jcl` on the classpath.
-The simplest way to do that is through the starters, which all depend on `spring-boot-starter-logging`.
+The recommended way to do that is through the starters, which all depend on `spring-boot-starter-logging`.
 For a web application, you need only `spring-boot-starter-web`, since it depends transitively on the logging starter.
 If you use Maven, the following dependency adds logging for you:
 
@@ -1395,7 +1395,7 @@ Spring Boot supports https://logging.apache.org/log4j/2.x[Log4j 2] for logging c
 If you use the starters for assembling dependencies, you have to exclude Logback and then include log4j 2 instead.
 If you do not use the starters, you need to provide (at least) `spring-jcl` in addition to Log4j 2.
 
-The simplest path is probably through the starters, even though it requires some jiggling with excludes.
+The recommended path is through the starters, even though it requires some jiggling with excludes.
 The following example shows how to set up the starters in Maven:
 
 [source,xml,indent=0,subs="verbatim,quotes,attributes"]
@@ -1733,8 +1733,7 @@ See {spring-boot-autoconfigure-module-code}/orm/jpa/HibernateJpaAutoConfiguratio
 Hibernate {hibernate-docs}#caching[second-level cache] can be configured for a range of cache providers.
 Rather than configuring Hibernate to lookup the cache provider again, it is better to provide the one that is available in the context whenever possible.
 
-If you're using JCache, this is pretty easy.
-First, make sure that `org.hibernate:hibernate-jcache` is available on the classpath.
+To do this with JCache, first make sure that `org.hibernate:hibernate-jcache` is available on the classpath.
 Then, add a `HibernatePropertiesCustomizer` bean as shown in the following example:
 
 [source,java,indent=0]
@@ -1765,10 +1764,9 @@ Spring Boot auto-configuration switches off its entity manager in the presence o
 
 [[howto-use-two-entity-managers]]
 === Use Two EntityManagers
-Even if the default `EntityManagerFactory` works fine, you need to define a new one.
-Otherwise, the presence of the second bean of that type switches off the default.
-To make it easy to do, you can use the convenient `EntityManagerBuilder` provided by Spring Boot.
-Alternatively, you can just the `LocalContainerEntityManagerFactoryBean` directly from Spring ORM, as shown in the following example:
+Even if the default `EntityManagerFactory` works fine, you need to define a new one, otherwise the presence of the second bean of that type switches off the default.
+You can use the `EntityManagerBuilder` provided by Spring Boot to help you to create one.
+Alternatively, you can use the `LocalContainerEntityManagerFactoryBean` directly from Spring ORM, as shown in the following example:
 
 [source,java,indent=0,subs="verbatim,quotes,attributes"]
 ----
@@ -2158,7 +2156,7 @@ Overriding the error page with your own depends on the templating technology tha
 For example, if you use Thymeleaf, you can add an `error.html` template.
 If you use FreeMarker, you can add an `error.ftl` template.
 In general, you need a `View` that resolves with a name of `error` or a `@Controller` that handles the `/error` path.
-Unless you replaced some of the default configuration, you should find a `BeanNameViewResolver` in your `ApplicationContext`, so a `@Bean` named `error` would be a simple way of doing that.
+Unless you replaced some of the default configuration, you should find a `BeanNameViewResolver` in your `ApplicationContext`, so a `@Bean` named `error` would be one way of doing that.
 See {spring-boot-autoconfigure-module-code}/web/servlet/error/ErrorMvcAutoConfiguration.java[`ErrorMvcAutoConfiguration`] for more options.
 
 See also the section on "`<<boot-features-error-handling, Error Handling>>`" for details of how to register handlers in the servlet container.
@@ -2731,8 +2729,7 @@ TIP: Take a look at Spring Boot's sample applications for a {spring-boot-code}/s
 
 [[howto-convert-an-existing-application-to-spring-boot]]
 === Convert an Existing Application to Spring Boot
-For a non-web application, it should be easy to convert an existing Spring application to a Spring Boot application.
-To do so, throw away the code that creates your `ApplicationContext` and replace it with calls to `SpringApplication` or `SpringApplicationBuilder`.
+To convert an existing non-web Spring application to a Spring Boot application, replace the code that creates your `ApplicationContext` and replace it with calls to `SpringApplication` or `SpringApplicationBuilder`.
 Spring MVC web applications are generally amenable to first creating a deployable war application and then migrating it later to an executable war or jar.
 See the https://spring.io/guides/gs/convert-jar-to-war/[Getting Started Guide on Converting a jar to a war].
 
@@ -2767,7 +2764,7 @@ If you have other features in your application (for instance, using other servle
 * A `@Bean` of type `Servlet` or `ServletRegistrationBean` installs that bean in the container as if it were a `<servlet/>` and `<servlet-mapping/>` in `web.xml`.
 * A `@Bean` of type `Filter` or `FilterRegistrationBean` behaves similarly (as a `<filter/>` and `<filter-mapping/>`).
 * An `ApplicationContext` in an XML file can be added through an `@ImportResource` in your `Application`.
-  Alternatively, simple cases where annotation configuration is heavily used already can be recreated in a few lines as `@Bean` definitions.
+  Alternatively, cases where annotation configuration is heavily used already can be recreated in a few lines as `@Bean` definitions.
 
 Once the war file is working, you can make it executable by adding a `main` method to your `Application`, as shown in the following example:
 
@@ -2871,7 +2868,7 @@ You can do so by adding a `WEB-INF/weblogic.xml` file with the following content
 === Use Jedis Instead of Lettuce
 By default, the Spring Boot starter (`spring-boot-starter-data-redis`) uses https://github.com/lettuce-io/lettuce-core/[Lettuce].
 You need to exclude that dependency and include the https://github.com/xetorthio/jedis/[Jedis] one instead.
-Spring Boot manages these dependencies to help make this process as easy as possible.
+Spring Boot manages both of these dependencies so you can switch to Jedis without specifying a version.
 
 The following example shows how to do so in Maven: