chore(docs): improve docs clarity and wording

Author: alexhambley

docs/api.md

@@ -3,7 +3,7 @@
 The examples below use the Compose stack's local address, `http://localhost:5001`. Note that the service serves its own OpenAPI specification at `/docs`.
 
 !!! note
-    `POST /v1/ro_crates/validate_metadata` is always available, but the **storage-backed endpoints** are only available when the service runs with `STORAGE_ENABLED=true` (see [Installation & Setup](installation.md#enabling-object-storage)); without this set, requests return `404`. 
+    `POST /v1/ro_crates/validate_metadata` is always available, but the **storage-backed endpoints** are only available when the service runs with `STORAGE_ENABLED=true` (see [Installation & Setup](installation.md#enabling-object-storage)); without this set, `POST /v1/ro_crates/{crate_id}/validation` or `GET /v1/ro_crates/{crate_id}/validation` requests will return a `404` result. 
 
 ## Validate metadata
 
@@ -14,18 +14,22 @@ This validates the contents of an `ro-crate-metadata.json` document and returns
 | Field | Required | Description |
 |-------|----------|-------------|
 | `crate_json` | yes | The metadata document, as a JSON string |
-| `profile_name` | no | Profile to validate against, e.g. `ro-crate-1.2`; defaults to `ro-crate-1.1` when omitted |
+| `profile_name` | no | Profile to validate against, e.g. `ro-crate-1.2`. The validator will default to `ro-crate-1.1` when this is omitted |
 
 !!! warning
     Currently, the validation profile is not detected from the RO-Crate. In other words, a `conformsTo` declaration in the metadata does not influence which validation profile is used by the validator, and the validation always runs against `profile_name`, or `ro-crate-1.1` when it is omitted.
 
-To validate a file:
+To validate an ro-crate metadata file:
 
 ```bash
 jq -Rs '{crate_json: .}' ro-crate-metadata.json | curl -X POST http://localhost:5001/v1/ro_crates/validate_metadata -H 'Content-Type: application/json' -d @-
 ```
 
-To choose a profile, add it to the `jq` object: `jq -Rs '{crate_json: ., profile_name: "ro-crate-1.2"}' ro-crate-metadata.json`.
+To choose a profile, add it to the json object as a `profile_name` entry:
+
+```bash
+jq -Rs '{crate_json: ., profile_name: "ro-crate-1.2"}' ro-crate-metadata.json | curl -X POST http://localhost:5001/v1/ro_crates/validate_metadata -H 'Content-Type: application/json' -d @-
+```
 
 | Code | Meaning |
 |------|---------|
@@ -36,7 +40,7 @@ To choose a profile, add it to the `jq` object: `jq -Rs '{crate_json: ., profile
 
 `POST /v1/ro_crates/{crate_id}/validation`
 
-This queues validation of an RO-Crate held in the object store. The RO-Crate is resolved first, so a missing or ambiguous crate ID may be reported; the validation itself runs on a worker. 
+This queues validation of an RO-Crate held in the object store. The RO-Crate is resolved first, so a missing or ambiguous crate ID may be reported immediately; the validation process itself runs asynchronously on a worker. 
 
 !!! note
     See [Crate IDs](#crate-ids) for how `{crate_id}` maps to objects in the bucket.
@@ -54,7 +58,7 @@ curl -X POST http://localhost:5001/v1/ro_crates/my-dataset-2026/validation -H 'C
 |------|---------|
 | `202` | Queued; the body is `{"message": "Validation in progress"}` |
 | `400` | Invalid Crate ID |
-| `404` | No RO-Crate at the expected keys, or storage mode is not enabled |
+| `404` | Either storage mode is not enabled, or there is no RO-Crate at the location defined by the given Crate ID |
 | `409` | Both a zip and a directory exist for this Crate ID |
 | `422` | Request body invalid |
 | `503` | Object store unreachable |
@@ -73,7 +77,7 @@ curl http://localhost:5001/v1/ro_crates/my-dataset-2026/validation
 |------|---------|
 | `200` | The stored result, including persisted `error` results |
 | `400` | Invalid Crate ID |
-| `404` | No result stored for this Crate ID yet |
+| `404` | No result stored for this Crate ID |
 
 ## Validation results
 
@@ -93,8 +97,8 @@ An RO-Crate's `status` can be:
 | `status` | Meaning |
 |----------|---------|
 | `valid` | The RO-Crate conforms to the profile |
-| `invalid` | Validated, but with conformance issues listed in `detail` |
-| `error` | The validation could not run; the reason is in an `error` field instead of `detail` |
+| `invalid` | The RO-Crate does not conform to the profile, issues listed in `detail` field |
+| `error` | The validation could not run; the reason is in an `error` field. No `detail` field is provided |
 
 !!! note
     `detail` contains the complete validation report. `created_at` is the UTC time of a stored-crate validation, and `null` for metadata-only validation, which does not set it. `profile` is the requested profile name, or `null` when the default (`ro-crate-1.1`) was used.

docs/contribution.md

@@ -33,7 +33,7 @@ Here `--build` matters: without it, Compose reuses the previously built image an
 
 ## Tests
 
-Install the development dependencies, then run the unit tests, which need no Docker:
+Install the development dependencies, then run the unit tests, which do not use Docker Engine:
 
 ```bash
 pip install -r requirements-dev.txt
@@ -43,7 +43,7 @@ pip install -r requirements-dev.txt
 pytest --ignore=tests/test_integration.py
 ```
 
-The integration tests bring up the full Compose stack (including the object store) and seed crates with `boto3`, so they need Docker running:
+The integration tests bring up the full Compose stack (including the object store) and seed crates with `boto3`, for which they need Docker Engine to be running:
 
 ```bash
 pytest tests/test_integration.py
@@ -61,7 +61,7 @@ ruff check . && ruff format --check .
 
 ## Dependencies
 
-Direct dependencies are declared in `pyproject.toml`; the `requirements*.txt` files are locks generated with pip-compile:
+Direct dependencies are declared in `pyproject.toml`; while the `requirements*.txt` files are locks generated using `pip-compile`:
 
 ```bash
 pip-compile pyproject.toml -o requirements.txt
@@ -73,11 +73,11 @@ pip-compile --extra dev pyproject.toml -o requirements-dev.txt
 
 ## Continuous Integration
 
-Pull requests to `develop` run three workflows: unit tests, integration tests (which start the Compose stack), and lint (`ruff check` and `ruff format --check`).
+Pull requests to `develop` will trigger three workflows: unit tests, integration tests (which start the Compose stack), and lint (`ruff check` and `ruff format --check`).
 
 ## How the API works
 
-The API process handles HTTP and runs metadata-only validation inline. Object storage-backed validation is queued through Redis to a Celery worker, which reads the crate from the S3-compatible store, validates it, and writes the result back:
+The API server handles HTTP and runs metadata-only validation inline. Object storage-backed validation is queued through Redis to a Celery worker, which reads the crate from the S3-compatible store, validates it, and writes the result back:
 
 ```mermaid
 flowchart LR

docs/index.md

@@ -1,12 +1,12 @@
 # RO-Crate Validation Service
 
-The RO-Crate Validation Service evaluates whether [RO-Crates](https://www.researchobject.org/ro-crate/) conform to the RO-Crate specification and to community profiles. The service wraps the [`rocrate-validator`](https://rocrate-validator.readthedocs.io/) library in a REST API, and is deployed as a Docker image. The RO-Crate Validation Service enables pipelines, other services, and Trusted Research Environments (TREs) to validate an RO-Crate over HTTP without running the validator themselves.
+The RO-Crate Validation Service provides a REST API for evaluating whether an [RO-Crate](https://www.researchobject.org/ro-crate/) conforms to a given RO-Crate profile. The service wraps the [`rocrate-validator`](https://rocrate-validator.readthedocs.io/) library, enabling pipelines, other services, and Trusted Research Environments (TREs) to validate an RO-Crate over HTTP without having to install the validator themselves.
 
 ## RO-Crates and profiles in brief
 
-An [RO-Crate](https://www.researchobject.org/ro-crate/) packages research data together with structured, machine-readable metadata: a JSON-LD file named `ro-crate-metadata.json`. Validating an RO-Crate evaluates that metadata against a **profile**. A profile is a set of requirements the RO-Crate must satisfy. That can be the base requirements of the [RO-Crate specification](https://www.researchobject.org/ro-crate/1.2/) itself, or a [community profile](https://www.researchobject.org/ro-crate/profiles) that adds domain-specific rules, such as the [Five Safes RO-Crate profile](https://trefx.uk/5s-crate/) for working with sensitive data in TREs.
+An [RO-Crate](https://www.researchobject.org/ro-crate/) packages research data together with structured, machine-readable metadata: a JSON-LD file named `ro-crate-metadata.json`. Validating an RO-Crate involves evaluating that metadata against a given **profile**. A profile is a set of requirements the RO-Crate must satisfy, either the base requirements of the [RO-Crate specification](https://www.researchobject.org/ro-crate/1.2/) itself, or a [community profile](https://www.researchobject.org/ro-crate/profiles) that adds domain-specific rules to the base specification. An example of a community profile is the [Five Safes RO-Crate profile](https://trefx.uk/5s-crate/), designed for researchers working with sensitive data in Trusted Research Environments (TREs).
 
-Whilst the validation checks themselves are performed by [`rocrate-validator`](https://rocrate-validator.readthedocs.io/), this service is a deployable HTTP wrapper around that tool: it adds a web API, asynchronous processing, and object-storage integration. The base validation rules come from the validator itself; we additionally package our own [Five Safes RO-Crate profile](five-safes.md) rules with the service for working in TREs.
+Whilst the validation checks themselves are performed by the [`rocrate-validator`](https://rocrate-validator.readthedocs.io/), this service is a deployable HTTP wrapper around that tool: it adds a web API, asynchronous processing, and object-storage integration. The base RO-Crate specification, as well as several [community profiles](https://rocrate-validator.readthedocs.io/en/latest/#features), are provided with the validator itself. We additionally package our own [Five Safes RO-Crate profile](five-safes.md) rules with the service for working in TREs.
 
 ## Validation methods