More improvements in the REST API documentation index

- Rewrite the output format section to remove repeated information
  about pretty-printed JSON.

- Replace another instance of "is used" with "is returned".

- Minor fixes in the 405 and 409 response sections.

Change-Id: I150e24d4d39744120f478b912b34e5061f6c93fb

Documentation/rest-api.txt

diff --git a/Documentation/rest-api.txt b/Documentation/rest-api.txt
index ec96eb9..b228dda 100644
--- a/Documentation/rest-api.txt
+++ b/Documentation/rest-api.txt
@@ -50,17 +50,22 @@
 
 [[output]]
 === Output Format
-Most APIs return pretty printed JSON by default. Compact JSON can be
-requested by setting the `Accept` HTTP request header to include
-`application/json`, for example:
+JSON responses are encoded using UTF-8 and use content type
+`application/json`.
+
+By default most APIs return pretty-printed JSON, which uses extra
+whitespace to make the output more readable for humans.
+
+Compact JSON can be requested by setting the `pp=0` query parameter,
+or by setting the `Accept` HTTP request header to include `application/json`:
 
 ----
   GET /projects/ HTTP/1.0
   Accept: application/json
 ----
 
-JSON responses are encoded using UTF-8 and use content type
-`application/json`.
+Producing (and parsing) the non-pretty compact format is more efficient,
+so tools should request it whenever possible.
 
 To prevent against Cross Site Script Inclusion (XSSI) attacks, the JSON
 response body starts with a magic prefix line that must be stripped before
@@ -71,12 +76,6 @@
   [ ... valid JSON ... ]
 ----
 
-The default JSON format is pretty, which uses extra whitespace to make
-the output more readable for a human. Producing (and parsing) the
-non-pretty compact format is more efficient so tools should request it
-by using the `Accept: application/json` header or `pp=0` query
-parameter whenever possible.
-
 Responses will be gzip compressed by the server if the HTTP
 `Accept-Encoding` request header is set to `gzip`. This may
 save on network transfer time for larger responses.
@@ -84,7 +83,7 @@
 [[timestamp]]
 === Timestamp
 Timestamps are given in UTC and have the format
-"'yyyy-mm-dd hh:mm:ss.fffffffff'" where "'ffffffffff'" indicates the
+"'yyyy-mm-dd hh:mm:ss.fffffffff'" where "'ffffffffff'" represents
 nanoseconds.
 
 [[encoding]]
@@ -133,7 +132,7 @@
 support the operation.
 
 E.g. some of the `/groups/` endpoints are only supported for Gerrit
-internal groups, if they are invoked for an external group the response
+internal groups; if they are invoked for an external group the response
 is `405 Method Not Allowed`.
 
 ==== 409 Conflict
@@ -144,7 +143,7 @@
 `409 Conflict` because the state of the change doesn't allow the submit
 operation.
 
-`409 Conflict` is also used if you try to create a resource but the
+`409 Conflict` is also returned if you try to create a resource but the
 name is already occupied by an existing resource.
 
 ==== 412 Precondition Failed