# Review version screenshots

## Review screenshots for a project version

A project version is the set of documentation content you are preparing for review. Screenshot
review is the check you make before publishing a documentation version to confirm
that its screenshot placeholders have usable images. Coverage is the percentage used to decide
whether the version's screenshot set needs attention. Use review when a version is ready, when
coverage is below 80%, or when a route's image is missing, stale, or needs replacement.
Screenshot management brings the version's visual records together so you can correct them before
the version moves on to publishing.

| If you need to… | Go to |
|---|---|
| See the screenshot summary during version review | [Finish the version review](#finish-the-version-review) |
| Open the version's screenshot list | [Open the version's screenshots](#open-the-versions-screenshots) |
| Understand the screenshot states | [Screenshot status reference](doc:screenshot-status-reference) |
| Review the broader screenshot feature | [Screenshots overview](doc:screenshots-overview) |
| Manage the project version around the screenshot list | [Project versions](doc:project-versions) |
| Continue with the published result | [Published documentation](doc:published-documentation) |

## Before you start

Before you begin, select the project and version whose route images you want to review. A status is
the label that tells you the condition of a screenshot, such as `Fresh`, `Stale`, or `Missing`.

**Prerequisites**

| Have or know | Why it matters |
|---|---|
| A selected project | The selected project supplies the versions and screenshot list. |
| A documentation version | The selected version supplies the screenshots to review. |
| The project's site URL | Have the site address ready for the route you select. |
| The route or document you need to review | The list identifies each screenshot by its route path and document. |
| The version's current status and coverage | Coverage tells you whether missing or stale images need attention before publishing. |

The version selector lists one option for each version available to the selected project. Each
option shows the version number and its lower-case status. The selector chooses the active version
first when one is available; otherwise, it chooses the first version in the returned list.

The available version choices, their values, and the number of choices depend on the selected
project's version list.

## Open the version's screenshots

If you are already checking the version, open screenshot management from version review. Use the
enterprise screenshot surface when you need the full list and its maintenance actions.

**Prerequisites**

- A project is selected.
- A project version is available.

**Steps**

1. On the version review page, select **Manage screenshots →**.
   Screenshot management opens for the project version.
2. In the version selector, choose the version number and status you need to inspect.
   The list changes to that version's screenshot placeholders.

**Result:** The screenshot list is open for the project version you are reviewing.

## Understand the screenshot screen

Screenshot management is a working list of route images attached to one documentation version.
Staleness tells you whether a route may have changed and needs a fresh image.
Use the status view to narrow the list, **Rows per page** to choose how many rows to see, and
the table to identify the route, document, status, age, and staleness information.

Use these controls and areas:

| What you need to do | What you use | What appears |
|---|---|---|
| Choose the documentation version | The version selector | One option per available version, showing its version number and lower-case status |
| Narrow the list | The status filter | `All`, `Fresh`, `Carried`, `Stale`, and `Missing` |
| Set the number of rows | **Rows per page** | `10` or `15` |
| Select rows | **Select all on page** or a row checkbox | A selected-row count and bulk actions when at least one row is selected |
| Inspect a listed screenshot | **View** | Opens route and status details |
| Correct a missing screenshot | **Capture** or **Upload** | Add an image to the missing row |
| Refresh an existing image | **Recapture** | Available for carried, stale, warning, or valid rows |

After you identify the status and available action, continue with [Review and update a screenshot](#review-and-update-a-screenshot).

When you open a preview, you can select **Close**. When the image is available, you can also select
**Annotate**, **Recapture**, **Upload replacement**, or **Remove from doc**. Without a selected
project, you see `No project selected` and a direction to select a project from the header. When
the filtered list has no rows, you see `No screenshots found`.

## Review and update a screenshot

Use this procedure when a row needs inspection or when its image must be replaced. Choose the
action that matches the row's status; the list does not offer the same row actions for every state.

**Prerequisites**

- A project is selected.
- The screenshot list is open for the version you want to maintain.
- Have the project's site URL ready before selecting **Capture**.

**Steps**

1. In the row you need to inspect, select **View**.
   Check the details before choosing a correction.
2. Read the staleness analysis before choosing a correction.
   A preview without an image says `No screenshot captured yet`. Read the matching message:
    `Route component unchanged — likely valid.` for a current route,
   `No screenshot has been captured for this route yet.` for a missing image. For a changed route,
   choose a fresh image.
3. Choose the action that matches your correction.

   | If you need to… | Select |
   |---|---|
   | Add callouts to an available image | **Annotate** |
   | Refresh the route image | **Recapture** |
   | Upload an image file | **Upload** or **Upload replacement** |
   | Remove the screenshot placeholder | **Remove from doc** |
   | Leave without changing the image | **Close** or **Cancel** |

4. If you selected **Recapture**, review the page address in the URL field.
   The field is labelled `Enter the URL to capture…` and accepts the address to preview.
5. If you selected **Recapture**, select **Preview**.
   The preview loads before the replacement can be saved.
6. If you selected **Recapture**, select **Save this screenshot**.
   The success state says `Screenshot captured` and `Saved to your project`.
7. If you selected **Upload** or **Upload replacement**, choose the replacement image through the
   file picker.

**Result:** The selected screenshot is reviewed or updated.

After updating a screenshot, use its status to choose a bulk action or recover from a message.

## Handle status and bulk-action branches

Screenshot status tells you which correction route is available. Use the status shown in the row,
not the route name, to choose the next action.

| Status or selection | Actions available |
|---|---|
| `Missing` | **View** is not listed; use **Capture** or **Upload**. |
| `Fresh` | Use **View** to inspect the current image. |
| `Carried` | Use **View** or **Recapture** to inspect or refresh the carried image. |
| `Stale` | Use **View** or **Recapture** to inspect the changed route and refresh its image. |
| `Valid` | Use **View** or **Recapture** to inspect or refresh the image. |
| `Warning` | Use **View** or **Recapture** to inspect or refresh the image. |
| At least one row selected | Use **Recapture**, **Remove placeholders**, or **Mark not needed** from the bulk-actions bar. |

**Prerequisites**

- The screenshot list is open.
- For a bulk action, at least one row is selected.

**Steps**

1. Select the row checkbox for each screenshot you want to handle together.
   The bulk-actions bar appears with the selected count.
2. Choose one bulk action.

   | If you need to… | Select |
   |---|---|
   | Refresh the selected routes | **Recapture** |
   | Remove the selected placeholders | **Remove placeholders** |
   | Keep the selected routes out of the required screenshot work | **Mark not needed** |

3. Review the resulting list before continuing with version review.
   The selected rows are cleared after the bulk request, and the list reloads.

**Result:** The selected rows reflect the bulk action, and the list is ready for another review.

When a message appears, follow the matching row below.

## Recover after an error

Read the message you see, then choose the matching action below.

| What you see | What to do |
|---|---|
| `Loading review data…` | Wait for the review data to finish loading. |
| `Review failed to load.` / `Reload the page to try again.` | Reload the page. |
| `No project selected` | Select a project from the header dropdown. |
| `No screenshots found` | Choose another status view or confirm that the selected version has screenshot placeholders. |
| `Preview failed` | Select **Try again** after correcting the URL. |
| `Enter a URL and click Preview` | Enter the page address, then select **Preview**. |
| `Preview a URL first, then save` | Preview the address before selecting **Save this screenshot**. |
| `Preview loaded — click Save to use this screenshot` | Select **Save this screenshot**. |
| `Screenshot coverage is below 80%.` / `Consider capturing missing screenshots before publishing.` | Select **Capture** for missing screenshots before publishing. |

**Prerequisites**

- The message you need to address is visible.

**Steps**

1. Read the message and find its matching action in the table.
2. Select the named recovery control, such as **Try again**, or reload the page when the message
   instructs you to do so.
3. Return to the screenshot row and review its status again.

**Result:** The message has a matching corrective action, and the screenshot row is ready for review.

When the screenshot summary is ready, continue with [Finish the version review](#finish-the-version-review).

## Finish the version review

When screenshot coverage is ready, return to the version review actions. Resolve flagged documents
before publishing. When screenshot coverage is below 80% and placeholders exist, you see
`Screenshot coverage is below 80%.` and `Consider capturing missing screenshots before publishing.`

**Prerequisites**

- You have reviewed the screenshot summary for the version.
- You know whether missing or stale screenshots still need attention.

**Steps**

1. Choose the next version action.

   | If you need to… | Select |
   |---|---|
   | Leave the version in draft form | **Save as draft** |
   | Send the version for another person's review | **Request approval** |
   | Publish a version with no flagged documents | **Publish v<version>** |

   After selecting **Request approval**, you see `Approval requested. A reviewer will be notified.`

**Result:** The version is saved as a draft, sent for approval, or published through the action you
selected.

## Message inventory

| Message | Owning screen |
|---|---|
| `Source code may have changed. UI could look different now.` | `Screenshots` |