Review and add fixes.

docs/src/main/asciidoc/_project-features-contract.adoc

@@ -6,7 +6,9 @@ Spring Cloud Contract supports out of the box following types of DSL.
 
 * written in `Groovy`
 * written in `YAML`
-* written in `Java`
+
+TIP: If you're not familiar with Groovy, don't worry - you can use Java syntax in the
+Groovy DSL files as well.
 
 If you decide to write the contract in Groovy, do not be alarmed if you have not used Groovy
 before. Knowledge of the language is not really needed, as the Contract DSL uses only a
@@ -43,9 +45,6 @@ TIP: You can compile contracts to stubs mapping using standalone maven command:
 [[contract-limitations]]
 === Limitations
 
-WARNING: Spring Cloud Contract Verifier does not properly support XML. Please use JSON or
-help us implement this feature.
-
 WARNING: The support for verifying the size of JSON arrays is experimental. If you want
 to turn it on, please set the value of the following system property to `true`:
 `spring.cloud.contract.verifier.assert.size`. By default, this feature is set to `false`.
@@ -64,7 +63,6 @@ The following sections describe the most common top-level elements:
 * <<contract-dsl-name>>
 * <<contract-dsl-ignoring-contracts>>
 * <<contract-dsl-passing-values-from-files>>
-* <<contract-dsl-http-top-level-elements>>
 
 [[contract-dsl-description]]
 ==== Description
@@ -205,8 +203,18 @@ include::{verifier_core_path}/src/test/resources/yml/contract_pdf.yml[indent=0]
 
 IMPORTANT: You should use this approach whenever you want to work with binary payloads both for HTTP and messaging.
 
+[[features-http]]
+== Contracts for HTTP
+
+Spring Cloud Contract allows you to verify applications that use REST or HTTP as a
+means of communication. Spring Cloud Contract verifies that for a request that matches the
+criteria from the `request` part of the contract, the server provides a response that is in
+keeping with the `response` part of the contract. Subsequently, the contracts are used to
+generate wiremock stubs that for any request matching the provided criteria, will provide a
+suitable response.
+
 [[contract-dsl-http-top-level-elements]]
-==== HTTP Top-Level Elements
+=== HTTP Top-Level Elements
 
 The following methods can be called in the top-level closure of a contract definition.
 `request` and `response` are mandatory. `priority` is optional.
@@ -1150,8 +1158,8 @@ response:
 ====
 
 [[contract-dsl-xml]]
-=== XML Support for REST
-For REST contracts, we also support XML request and response body.
+=== XML Support for HTTP
+For HTTP contracts, we also support XML request and response body.
 The XML body has to be passed within the `body` element
 as a `String` or `GString`. Also body matchers can be provided for
 both request and response. In place of the `jsonPath(...)` method, the `org.springframework.cloud.contract.spec.internal.BodyMatchers.xPath`

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

@@ -32,13 +32,13 @@ starting out with {project-full-name}, try one of the https://spring.io/guides[g
 * Ask a question. We monitor https://stackoverflow.com[stackoverflow.com] for questions
 tagged with https://stackoverflow.com/tags/{project-name}[`{project-name}`].
 * Report bugs with {project-full-name} at https://github.com/spring-cloud/{project-name}/issues.
+* Chat with us at http://https://gitter.im/spring-cloud/{project-name}[{project-full-name} Gitter]
 
 NOTE: All of {project-full-name} is open source, including the documentation. If you find
 problems with the docs or if you want to improve them, please {github-code}[get
 involved].
 
 
-
 [[contract-documentation-first-steps]]
 == First Steps
 If you are getting started with {project-full-name} or 'Spring' in general, start with
@@ -50,8 +50,8 @@ If you are getting started with {project-full-name} or 'Spring' in general, star
 <<getting-started.adoc#getting-started-first-application, First application>>
 * *Tutorial:*
 <<getting-started.adoc#getting-started-cdc, Introduction>> |
-<<getting-started.adoc#consumer-side-loan-issuance, Consumer >> |
-<<getting-started.adoc#producer-side-fraud-detection-server, Producer Part 1>> |
+<<getting-started.adoc#consumer-side-loan-issuance, Consumer Part 1>> |
+<<getting-started.adoc#producer-side-fraud-detection-server, Producer>> |
 <<getting-started.adoc#consumer-side-loan-issuance-final-step, Consumer Part 2>>
 
 
@@ -73,7 +73,15 @@ you covered>>:
 ** <<using.adoc#flows-cdc-contracts-external,Consumer Driven Contracts with contracts in external repo>>
 ** <<using.adoc#flows-cdc-contracts-stubs-git,Consumer Driven Contracts with contracts on the producer side, pushed to git>>
 
+TIP: We talk about *Provider Contracts* when it's the producer of the API that defines the contracts and
+publishes it for all its consumers to use. This approach is useful for producers that can't
+directly collaborate with their consumers; for example, when there are too many consumers,
+the consumers are external (don't work within the same company).
 
+TIP: We use the term *Consumer-Driven Contracts* to refer to workflows where the consumers of an API
+play a vital role in the process of creating the contracts; it's the recommended approach, easy
+to implement when both producer and consumer teams work for the same organisations and the number
+of consumers is not extremely large.
 
 == Learning about {project-full-name} Features
 Need more details about {project-full-name}'s core features?
@@ -81,18 +89,20 @@ Need more details about {project-full-name}'s core features?
 
 * *Core Features:*
 <<project-features.adoc#contract-dsl, Contract DSL>> |
-<<project-features.adoc#features-messaging, Messaging>>
+<<project-features.adoc#features-http, Contracts for HTTP>> |
+<<project-features.adoc#features-messaging, Contracts for Messaging>>
 * *Integrations:*
 <<project-features.adoc#features-jax-rs, JAX-RS>> |
-<<project-features.adoc#features-webflux, WebFlux>> |
 <<project-features.adoc#features-context-paths, Context Paths>> |
 <<project-features.adoc#features-rest-docs, RESTDocs>>
+<<howto.adoc#how-to-generate-pact-from-scc, Pact>>
 * *Modules:*
 <<project-features.adoc#features-stub-runner, Stub Runner>> |
 <<project-features.adoc#features-wiremock, WireMock>>
-* *Build tools:*
-link:maven-project.html[Maven] |
-link:gradle-project.html[Gradle] |
+// TODO: links don't work in "build Tools" section
+* *Build Tools:*
+link:maven-project.html[Contract Verifier - Maven] |
+link:gradle-project.html[Contract Verifier - Gradle] |
 link:docker-project.html[Docker]
 
 

docs/src/main/asciidoc/getting-started.adoc

@@ -13,7 +13,7 @@ principles as we go.
 [[getting-started-introducing-spring-cloud-contract]]
 == Introducing Spring Cloud Contract
 
-Spring Cloud Contract moves TDD to the level of software architecture. It allows to perform consumer, consumer-driven and producer-driven contract testing.
+Spring Cloud Contract moves TDD to the level of software architecture. It allows to perform consumer-driven and producer-driven contract testing.
 
 [[getting-started-introducing-spring-cloud-contract-history]]
 === History
@@ -914,7 +914,7 @@ the server side. Currently, the consumer side work is done.
 [[getting-started-cdc-producer]]
 === Producer side (Fraud Detection server)
 
-As a developer of the Fraud Detection server (a server to the Loan Issuance service) we would like to:
+As a developer of the Fraud Detection server (a server to the Loan Issuance service) I would like to:
 
 - take over the pull request
 - write the missing implementation
@@ -1073,7 +1073,7 @@ application and the stub artifacts.
 [[getting-started-cdc-consumer-final]]
 === Consumer Side (Loan Issuance) Final Step
 
-As a developer of the Loan Issuance service (a consumer of the Fraud Detection server) we will want to:
+As a developer of the Loan Issuance service (a consumer of the Fraud Detection server) I will want to:
 
 - merge our feature branch to `master`
 - switch to online mode of working
@@ -1120,7 +1120,7 @@ include::{introduction_url}/samples/standalone/dsl/http-client/src/test/resource
 That's it!
 
 [[getting-started-whats-next]]
-== What to Read Next
+== Next Steps
 Hopefully, this section provided some of the {project-full-name} basics and got you on your way
 to writing your own applications. If you are a task-oriented type of developer, you might
 want to jump over to https://spring.io and check out some of the