A proofread turned shipwreck

README.adoc

@@ -63,8 +63,8 @@ include::complete/src/main/java/com/example/testingrestdocs/HomeController.java[
 
 == Run the Application
 
-The Spring Initializr creates a `main` class that you can use to launch the application.
-The following listing (from
+The Spring Initializr creates a `{YourProjectName}Application` class with a `main` method 
+that you can use to launch the application. The following listing (from
 `src/main/java/com/example/testingrestdocs/TestingRestdocsApplication.java`) shows the
 application class that the Spring Initializr created:
 
@@ -93,7 +93,8 @@ application. Did you notice that there is not a single line of XML? There is no
 file, either. This web application is 100% pure Java and you did not have to deal with
 configuring any plumbing or infrastructure. Spring Boot handles all of that for you.
 
-Logging output is displayed. The service should be up and running within a few seconds.
+Run main(). Logging output is displayed and the service should be running within a few 
+seconds.
 
 == Test the Application
 
@@ -105,13 +106,17 @@ part of the tests by using Spring REST Docs.
 
 The first thing you can do is write a simple sanity check test that fails if the
 application context cannot start. To do so, add Spring Test and Spring REST Docs as
-dependencies to your project, in the test scope. The following listing shows what to add
-if you use Maven:
+dependencies to your project, in the test scope.
+
+=== Maven
+
+If you use Maven, the following listing shows what to add to the `<dependencies>` 
+section of `pom.xml`:
 
 ====
 [source,xml]
 ----
-include::complete/pom.xml[tag=test]
+include::complete/pom.xml[tag=restdocs-dependency]
 ----
 ====
 
@@ -124,12 +129,14 @@ include::complete/pom.xml[]
 ----
 ====
 
-The following example shows what to add if you use Gradle:
+=== Gradle
+
+If you use Gradle, add the following line to the `dependencies` section of your `build.gradle` file.
 
 ====
 [source,groovy]
 ----
-include::complete/build.gradle[tag=test]
+include::complete/build.gradle[tag=restdocs-dependency]
 ----
 ====
 
@@ -142,7 +149,7 @@ include::complete/build.gradle[]
 ----
 ====
 
-NOTE: You can ignore the comments in the build files. They are there to let us pick up
+NOTE: You can ignore the `tag` comments in the build files. They are there to let us pick up
 parts of the files for inclusion in this guide.
 
 NOTE: You have included the `mockmvc` flavor of REST Docs, which uses Spring MockMvc to

complete/build.gradle

@@ -21,7 +21,9 @@ repositories {
 
 dependencies {
 	implementation 'org.springframework.boot:spring-boot-starter-web'
+	// tag::restdocs-dependency[]
 	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
+	// end::restdocs-dependency[]
 	testImplementation('org.springframework.boot:spring-boot-starter-test') {
 		exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
 	}

complete/pom.xml

@@ -23,20 +23,18 @@
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-web</artifactId>
 		</dependency>
-		<dependency>
-			<groupId>org.springframework.boot</groupId>
-			<artifactId>spring-boot-starter-test</artifactId>
-			<scope>test</scope>
-		</dependency>
+		<!-- tag::restdocs-dependency[] -->
 		<dependency>
 			<groupId>org.springframework.restdocs</groupId>
 			<artifactId>spring-restdocs-mockmvc</artifactId>
 			<scope>test</scope>
 		</dependency>
+		<!-- end::restdocs-dependency[] -->
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-test</artifactId>
 			<scope>test</scope>
+			<!-- We'll be using JUnit 5. Vintage is for JUnit 4 so we exclude it. -->
 			<exclusions>
 				<exclusion>
 					<groupId>org.junit.vintage</groupId>

initial/pom.xml

@@ -28,6 +28,7 @@
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-test</artifactId>
 			<scope>test</scope>
+			<!-- We'll be using JUnit 5. Vintage is for JUnit 4 so we exclude it. -->
 			<exclusions>
 				<exclusion>
 					<groupId>org.junit.vintage</groupId>