# Documentation job status reference

## Documentation job statuses at a glance

A documentation job status tells you where a documentation generation run stands and which
follow-up action belongs next. Use this page when you need to read a status on a project’s
**Activity & Jobs** surface or in **Operations**.

| If you need to… | Go to |
|---|---|
| Find the project job list | [Find the job status](#find-the-job-status) |
| Understand a status, progress value, or result column | [Interpret the status and progress details](#interpret-the-status-and-progress-details) |
| Refresh the list or respond to a completed, failed, or active run | [Respond to a job's status](#respond-to-a-jobs-status) |
| Resolve a loading, empty, refresh, or failure message | [When status information does not load](#when-status-information-does-not-load) |
| Start documentation work | [Run documentation work](doc:run-documentation-work) |
| Follow the generation stages | [Documentation generation lifecycle](doc:documentation-generation-lifecycle) |
| Review the wider operational hub | [Operations overview](doc:operations-overview) |
| Review past operational work | [Job History](doc:job-history) |

The project **Activity & Jobs** surface is the canonical list for a project’s background
documentation runs. The **Operations** surface also presents recent jobs with their status,
stage, document count, duration, and error information. A documentation generation lifecycle
has its own stage sequence; use [Documentation generation lifecycle](doc:documentation-generation-lifecycle)
when you need that sequence rather than a status lookup.

## Before you check a job status

Before reading a status, decide whether you are checking one project’s activity or the wider
recent-job view in **Operations**.

**Prerequisites**

- Know the project whose runs you want to review when using the project job surface.
- Open **Activity & Jobs** for the project whose runs you want to review.
- Open **Operations** when you need the recent-job view.

With the view identified, locate the job in the next section.

## Find the job status

Choose the project surface for one project’s activity or **Operations** for the recent-job table.

**Steps**

1. Choose one view:

   | If you want to… | Open |
   |---|---|
   | Review runs for one project | Open the project’s **Activity & Jobs** view |
   | Review recent jobs across the operational view | Open **Operations** |

2. In the project view, use **Recent Jobs** to locate the run’s status.
3. In **Operations**, use **Recent jobs** and read the value in its **Status** column.
4. Select **Refresh** to request the current list again.

While the project list is being refreshed, the action label changes to `Refreshing…`.

**Result:** The selected job list is on screen, and you can read the status from the project
**Recent Jobs** area or the **Status** column in **Recent jobs**.

![Recent jobs table in the Operations view](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/be4a16ceec07e8356faca1380e39e91e.png)

## Interpret the status and progress details

Read the current status on the project surface as **Completed**, **Failed**, **Running**, **Pending**,
or **Cancelled**.

| Status | What the status tells you | Details available on the surface |
|---|---|---|
| **Completed** | The run finished successfully. | The row can expand to a completion summary. |
| **Failed** | The run finished with a failure. | The row can expand to failure details. |
| **Running** | The run is active. | The list counts it as in progress and can show progress details. |
| **Pending** | The run is active but has not moved into the running work. | The list counts it as in progress and can show progress details. |
| **Cancelled** | The run was cancelled. | The status remains available for review, and delete controls can be available. |

**Running** and **Pending** are the active statuses. An active row can show the current stage
and percentage. When live progress is available, it can also show the current item, elapsed
time, and estimated remaining time. When live progress is not available, the row uses the job’s
basic stage and percentage instead.

The **Operations** view presents recent jobs in a table. Read **When** for the recorded time,
**Status** for the job status, **Stage** for the current stage, **Docs** for the document count,
**Duration** for the elapsed run time, and **Error** for error text.

In **Operations**, **Completed** uses the success chip and **Failed** uses the error chip. Other
status values use the warning fallback in that table.

With the status and its details read, choose the action that matches the row’s current state.

## Respond to a job's status

The actions available for a row depend on its status. Choose an action that matches the row’s current state.

### Refresh the job list

**Prerequisites**

The project job list is open.

**Steps**

1. Select **Refresh**.

The label changes to `Refreshing…` while the list is loading.

**Result:** The project job list remains on screen with the refreshed loading state, then returns
to the list when loading finishes.

### Cancel an active job

**Prerequisites**

The job is **Running** or **Pending**, and the row provides **Cancel**.

**Steps**

1. Select **Cancel** on the active job row.
2. Select **Are you sure?** to confirm the cancellation.

While cancellation is being processed, the action label is `Cancelling...`.

**Result:** The active job has received the cancellation request, and its status can be reviewed
again in the job list.

### Delete documents from a finished job

**Prerequisites**

The job is **Completed**, **Failed**, or **Cancelled**, and the row provides **Delete <n> Docs**
or **Delete Job**.

**Steps**

1. Select one control on the row:

   | If the job has… | Select |
   |---|---|
   | Created documents | **Delete <n> Docs** |
   | No created documents | **Delete Job** |

2. Select **Confirm Delete?** when the confirmation label appears.

The action label is `Delete <n> Docs` when the job has created documents; otherwise it is
`Delete Job`.

**Result:** The delete request has been sent for the selected finished job.

### Continue from a completed result

**Prerequisites**

The job is **Completed**, and its row can expand.

**Steps**

1. Open the completed job row.
2. Select one available action:

   | If you need to… | Select |
   |---|---|
   | Review flagged documents before publishing | **Review & Publish** |
   | Open documentation when a published URL is available | **View Published Documentation** |
   | Open documentation through the project fallback | **View Documentation** |
   | Copy the public documentation address | **Copy Public URL** |
   | Start another generation | **Generate Again** |

**Result:** The selected completion action opens its corresponding documentation, review,
address-copy, or generation path.

If the list instead shows a loading or failure message, use the table in the next section.

## When status information does not load

The job surfaces use different messages for initial loading, an empty project list, an empty
history, a failed refresh, and a failed job. Match the message on screen to the action in the
table.

| Message | When it appears | What to do |
|---|---|---|
| `Loading runs…` | The project list is loading before any runs are available. | Wait for the list to finish loading. |
| `No generation runs yet` | The project has no generation runs in the empty project state. | Select **Configure & run documentation generation →** to go to the generation configuration path. |
| `Jobs failed to load.` followed by the error message | The project list has an error and no jobs to display. | Select **Refresh** and try the list again. |
| `Failed to load job history:` followed by the error message | **Recent Jobs** has an error and no jobs to display. | Select the available refresh action and try again. |
| `Showing the last successful load — refreshing failed` followed by the error message | A refresh failed while jobs are already on screen. | Continue using the last successful list, then select **Refresh** again. |
| `Job Failed` followed by the error stage and error text when present | An expanded failed row is showing failure details. | Read the error stage and error text in the expanded row. |
| `Documentation Generated Successfully!` | An expanded completed result is showing its completion summary. | Continue with the completion action that matches your next task. |
| `Your documentation has been created and is ready to view` | The completion summary is available. | Select **View Published Documentation** or **View Documentation** when the corresponding action is present. |
| `Enriching documents with screenshots` | Screenshot enrichment progress is active in the completion summary. | Read the progress count while the documents update. |

When a stalled run’s progress remains quiet past the inactivity threshold, the project surface
describes it as reconciled to **Failed**. Read the failed row’s details rather than treating it
as an active run.

After resolving the status message, continue with the work that follows from the run’s state.

## What to do next

After you interpret the status, continue according to the work you need to do:

- Start or monitor documentation work in [Run documentation work](doc:run-documentation-work).
- Follow the generation stages in [Documentation generation lifecycle](doc:documentation-generation-lifecycle).
- Review the wider operational work areas in [Operations overview](doc:operations-overview).
- Review past operational work in [Job History](doc:job-history).

If a stalled run is shown as **Failed**, use the failed-row details and then follow the generation
or history path that matches your next task.