From f1a1ff678c0ad18981cdce79b2bd43a7af31cfc3 Mon Sep 17 00:00:00 2001
From: Aimee Ukasick <aimee.ukasick@hashicorp.com>
Date: Fri, 14 Feb 2025 09:47:11 -0600
Subject: [PATCH] Docs: Clarify Job status mapping on Job page (#25105)

* Add dead (stopped) to status mapping to clarify Stopped

CE-816

* Pull status mapping into partial and include in job status command

* change `complete` to dead in table after discuss with Michael

* added clarifications; add CLI status definitions

* fixed line endings

* fixed typoce816dead
---
 website/content/docs/commands/job/status.mdx |  2 +
 website/content/docs/concepts/job.mdx        | 40 +++++++++++---------
 website/content/partials/job-status-map.mdx  | 17 +++++++++
 3 files changed, 41 insertions(+), 18 deletions(-)
 create mode 100644 website/content/partials/job-status-map.mdx

diff --git a/website/content/docs/commands/job/status.mdx b/website/content/docs/commands/job/status.mdx
index 913618847..9cb1ec4c8 100644
--- a/website/content/docs/commands/job/status.mdx
+++ b/website/content/docs/commands/job/status.mdx
@@ -30,6 +30,8 @@ When ACLs are enabled, this command requires a token with the `read-job`
 capability for the job's namespace. The `list-jobs` capability is required to
 run the command with a job prefix instead of the exact job ID.
 
+@include 'job-status-map.mdx'
+
 ## General Options
 
 @include 'general_options.mdx'
diff --git a/website/content/docs/concepts/job.mdx b/website/content/docs/concepts/job.mdx
index 785546a3f..effaa1b10 100644
--- a/website/content/docs/concepts/job.mdx
+++ b/website/content/docs/concepts/job.mdx
@@ -26,26 +26,28 @@ job state matches your desired state.
 ## Job statuses
 
 After you submit your job, Nomad assigns a status to indicate how a job is
-performing. This status indicates how the job's current allocations compare to the desired
-job state.
+performing. This status indicates how the job's current allocations compare to
+the desired job state.
 
-Nomad uses one of three values to describe a job's status.
+@include 'job-status-map.mdx'
 
-- `complete`
-- `dead`
-- `running`
+### CLI statuses
 
-The CLI and API return these rigid statuses, which are useful for scheduling and
-garbage collection. However, the Nomad UI displays additional human-readable
-statuses to help you manage jobs.
+Only the CLI returns these job statuses.
 
-The following table maps the CLI and API statuses to the statuses that appear in the Nomad UI.
+#### `running`
 
-| CLI and API status | UI status |
-| ---------------    | --------------- |
-| `complete `        | `Complete`    |
-| `dead`             | `Failed`, `Scaled Down`, `Stopped` |
-| `running`          | `Degraded`, `Deploying`, `Healthy`, `Recovering`, `Running`, `Scaled Down` |
+The `running` status indicates that the job has non-terminal allocations.
+
+#### `dead`
+
+The `dead` status indicates that all evaluations and allocations are in a
+terminal state.
+
+#### `dead (stopped)`
+
+The `dead (stopped)` status indicates that a user has manually stopped the job.
+You may start this job again.
 
 ### UI statuses
 
@@ -53,12 +55,13 @@ These job statuses only appear in the Nomad UI.
 
 #### Complete
 
-The `Complete` status indicated that all expected allocations are complete. This
+The `Complete` status indicates that all expected allocations are complete. This
 status applies to batch and sysbatch jobs only.
 
 #### Degraded
 
-The `Degraded` status indicates that a [deployment] is not taking place. Some allocations are failed, lost, or unplaced.
+The `Degraded` status indicates that a [deployment] is not taking place. Some
+allocations are failed, lost, or unplaced.
 
 #### Deploying
 
@@ -70,7 +73,8 @@ The `Failed` status indicates that all allocations are failed, lost, or unplaced
 
 #### Healthy
 
-The `Healthy` status indicates that all expected allocations are running and healthy.
+The `Healthy` status indicates that all expected allocations are running and
+healthy.
 
 #### Recovering
 
diff --git a/website/content/partials/job-status-map.mdx b/website/content/partials/job-status-map.mdx
new file mode 100644
index 000000000..16322a24f
--- /dev/null
+++ b/website/content/partials/job-status-map.mdx
@@ -0,0 +1,17 @@
+Nomad uses one of these values to describe a job's status:
+
+- `dead`
+- `running`
+
+The CLI returns these rigid statuses, which are useful for scheduling and
+garbage collection. However, the Nomad UI displays additional human-readable
+statuses to help you manage jobs.
+
+The following table maps the CLI statuses to the statuses that appear in the
+Nomad UI.
+
+| CLI status       | UI status |
+| ---------------- | --------- |
+| `dead`           | `Complete`, `Failed`, `Scaled Down` |
+| `dead (stopped)` | `Stopped` |
+| `running`        | `Degraded`, `Deploying`, `Healthy`, `Recovering`, `Running`, `Scaled Down` |