cloud-docs/run-environment: Don't overload the term "run"

[apparentlymart]

What

I have revised the "Concurrency and Run Queuing" section of the "Run Environment" page in the HCP Terraform documentation, to avoid overloading the meaning of "run".

Rendered Preview

Why

This "Run Environment" page belongs to a collection of pages that together describe our capital-R concept of "Run" in HCP Terraform, which refers to the combination of a plan phase and an optional apply phase. "Normal" runs form a per-workspace queue where each run must be resolved (its plan either approved or declined) before proceeding with the next.

(That per-workspace queue of runs is not the same as the global queue of "jobs" that this section is discussing: a run that has already completed its planning and is waiting for approval does not exist in the job queue until someone approves the plan, causing the plan to be applied.)

This particular section was previously using "run" both in its usual meaning and with a new meaning of "job that can be picked up by a worker", which made this section hard to follow when considered in relation to everything else in this chapter of the documentation.

The prior text was already using the word "job" once to describe what was being taken from queues, and so here I've revised the text to consistently use that noun to refer to the kind of thing that is constrained by our concurrency limits. I think that explains the situation a little more clearly while avoiding getting too deep into the implementation details.

I also made the separate editorial decision that jobs take actions and so what they do should be described actively using e.g. the gerund "applying" instead of the nouned-verb "applies" (which is ambiguous with a verb as in "the agent applies the plan", making the prior sentence harder to parse).

Otherwise, I attempted to keep the message largely the same as it was before, but just using hopefully-clearer terminology.

Since the heading text also changed, I tincluded an additional anchor with the previously-used section slug to catch any existing links directly to this section.

---

Merge Checklist

Pull Request

• One or more labels describe the type of change (e.g. clarification) and associated product (e.g. HCP Terraform ).
• Description links to related pull requests or issues, if any.

Content

• Redirects have been added to website/redirects.js for moved, renamed, or deleted pages. (n/a)
• API documentation and the API Changelog have been updated. (n/a)
• Links to related content where appropriate (e.g., API endpoints, permissions, etc.). (n/a)
• Pages with related content are updated and link to this content when appropriate. (n/a)
• Sidebar navigation files have been updated for added, deleted, reordered, or renamed pages. (n/a)
• New pages have metadata (page name and description) at the top. (n/a)
• New images are 2048 px wide. (n/a)
• New code blocks have the correct syntax and line breaks to eliminate horizontal scroll bars. (n/a)
• UI elements (button names, page names, etc.) are bolded. (n/a)
• The Vercel website preview successfully deployed.

Reviews

• I or someone else reviewed the content for technical accuracy.
• I or someone else reviewed the content for typos, punctuation, spelling, and grammar.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
terraform-docs-common	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 16, 2024 5:13pm

[trujillo-adam]

Thanks for taking a run at this one!

[trujillo-adam]

Suggested change

	<a name="concurrency-and-run-queuing"></a>
	<a name="concurrency-and-run-queuing"></a>

We can do this in another PR, but instead of adding this anchor, we should search for the links to this heading update them.

[trujillo-adam]

Suggested change

	HCP Terraform uses multiple concurrent worker VMs, which take jobs from a global queue of operations that are ready to execute. (This includes both creating new plans and then applying those plans once they've been approved.)
	HCP Terraform uses multiple concurrent worker VMs, which take jobs from a global queue of operations that are ready to execute. This includes both creating new plans and then applying those plans once they've been approved.

Per the style guide, avoid using parentheses in prose.

[trujillo-adam]

Suggested change

	HCP Terraform can also delay some jobs to make performance more consistent across organizations. If an organization requests a large number of jobs at once, HCP Terraform queues some of them immediately, and delays the rest until some of the initial batch have finished; this allows every organization to continue executing jobs even during periods of especially heavy load.
	HCP Terraform can also delay some jobs to make performance more consistent across organizations. If an organization requests a large number of jobs at once, HCP Terraform queues some of them immediately and delays the rest until some of the initial batch have finished. Doing so allows every organization to continue executing jobs even during periods of especially heavy load.

I don't think the semicolon is wrong here, but I'd rather use two sentences to keep it simple.