Standard scope
Applies to: Primarily the tierpoint-prodtech scope (customer-facing and tenant provisioning runbooks); the underlying pattern is available to any scope documenting customer or tenant provisioning Domain: provisioning Status: Active
Provisioning standard
This standard defines the execution options pattern — a structured approach for documenting provisioning and deployment runbooks that need to support more than one way of running the same steps. It originates from TierPoint ProdTech's customer-deployment documentation, where a single provisioning task is frequently offered to the reader as several tabbed alternatives (manual portal steps, an orchestrated script, a standalone script). The pattern itself — organizing a runbook by execution context and presenting the alternatives side by side — is scope-agnostic and documented here as a base standard. The concrete tabbed implementation described later in this document, built on Docusaurus, is specific to the tierpoint-prodtech scope; see scope and implementation for what that means for other scopes.
This standard documents the pattern, not any specific customer runbook. No customer- or tenant-specific content is reproduced here.
When to use this pattern
Use the execution options pattern for any runbook that walks an engineer through provisioning or configuring infrastructure where more than one legitimate way to perform the task exists — for example, a task that can be done by hand in a portal or console, run as a script from a management host, or run as a fully self-contained script with no dependencies.
Do not use this pattern for:
- A task with only one possible execution method — write a single, linear procedure instead
- Fully automated deployments driven by IaC or a CI/CD pipeline (Terraform, Bicep, Ansible, pipeline stages) — those belong in the project's automation documentation, not in a provisioning runbook
- Purely informational or reference documentation with no procedural steps
A runbook author must classify a task's execution target before writing it, because the classification determines which execution options apply and how they are labeled. Do not start writing a multi-option task without first deciding what the execution target is.
Execution options
Every provisioning task that qualifies for this pattern is documented using two or three consistent execution options, distinguished by where and how the reader runs the commands, not by which specific tool they use:
| Option | Execution context | Description |
|---|---|---|
| Manual | Graphical interface, physical action, or web console | Steps a human performs directly — a cloud portal, a hardware management console, an on-site physical inspection, or a management console UI |
| Orchestrated script | Run from a management host | A configuration-driven script executed from a management workstation or jump host, reading its input from the project's shared environment configuration |
| Standalone script | Run anywhere | A self-contained script with no external dependencies — every value it needs is declared in a clearly marked configuration block at the top of the script, before any executable code |
Not every task needs all three. A task against a cloud control plane, for example, has no target node to run a script "on" — it is either a manual portal action, an orchestrated script call, or a standalone script call. A task against a piece of physical hardware may only offer a manual (vendor console) option, plus a scriptable option if the vendor exposes an API.
Choosing which options a task needs
Classify the task by its execution target, then apply the matching profile:
| Execution target | Typical options |
|---|---|
| Control-plane / cloud-API task (no target node) | Manual (web console) · Orchestrated script · Standalone script |
| On-host task (an operating system or node the reader can reach) | Manual (contextual console — whichever management tool is appropriate) · Orchestrated script (run from a management host) · Standalone script |
| Physical or vendor hardware task | Manual (vendor console) always; a scriptable option only if the vendor provides an API or CLI |
| Multi-vendor task where the underlying procedure differs by device | Present as tabs per device or vendor, not per execution method — the option pattern above does not apply the same way when the procedure itself differs by vendor |
| Fully automated / CI-CD / documentation-only task | No options — a single linear procedure |
Default and ordering
When a manual option exists, present it first and mark it as the default view for the reader. When no manual option exists (a task that can only be scripted), the orchestrated script option is the default.
Standalone script rule
Every standalone script variant must declare all of its configurable values in a single, clearly delimited configuration block at the top of the script, before any executable code. No variable may be defined in the body of the script or interleaved with logic. This is what makes a standalone script copy-paste ready: a reader edits only the values at the top, then runs the rest unmodified.
Orchestrated script contract
Every orchestrated script should expose a consistent parameter contract so that engineers moving between tasks do not have to relearn each script's interface: a path to the shared environment configuration, a way to override credential resolution, a way to scope the operation to specific targets, a dry-run switch, and a way to override the log output location. See the scripting standard for the full parameter and credential-resolution conventions scripts in this repository must follow.
Document organization
A provisioning runbook that covers a multi-step deployment is organized hierarchically, grouping related tasks into named stages, each broken into individual steps:
implementation/
├── stage-01-<description>/
│ ├── index # Stage overview: objective, tasks, validation, outcome
│ ├── task-01-<action> # Individual step, using the execution options pattern
│ ├── task-02-<action>
│ └── ...
├── stage-02-<description>/
│ └── ...
└── stage-03-<description>/
└── ...Stage and step identifiers use zero-padded two-digit numbers (01, 02, 03) so that file listings sort in execution order.
Stage overview requirements
Every stage's overview page states, at minimum:
| Section | Answers |
|---|---|
| Objective | Why this stage exists, in one sentence |
| Tasks | What gets done — a list that maps one-to-one with the stage's steps |
| Validation | How to verify the stage succeeded — a checkable list of success criteria |
| Outcome | What state the environment is in once the stage is complete, in one sentence |
| Navigation | Links to the previous stage, the parent index, and the next stage |
Step requirements
Every individual step includes:
- A short overview of what the step accomplishes, including any conditions under which it should be skipped
- The execution options relevant to that step, following the pattern above
- A validation section — a mix of a human-checkable checklist and, where practical, a command the reader can run to confirm success
- Navigation links to the previous step, the parent stage, and the next step
Validation
Every step's validation should combine, where applicable:
- A checklist — human-verifiable items the reader can tick off
- A verification command — something the reader can run inline to confirm the result
- A reference to a reusable validation script, if the project maintains one for that check
Scope and implementation
The execution options pattern itself — organizing provisioning steps by execution context and presenting manual, orchestrated, and standalone alternatives — is a base pattern available to any scope that documents customer- or tenant-facing provisioning.
The concrete implementation currently in use — tabbed navigation built on the Docusaurus documentation platform — is specific to the tierpoint-prodtech scope, because that scope's documentation site runs on Docusaurus. A scope whose documentation site runs on a different platform (for example MkDocs Material) should apply the same execution-options structure and the same classification rules, but implement the presentation using whatever tabbed or sectioned content mechanism its documentation platform supports. See the project's docs-platforms standard for which documentation platform a given repository's scope uses, and adapt the presentation layer accordingly — the underlying rules in this document (which options apply, how they are ordered, what each must contain) do not change based on the rendering technology.
Related standards
- Solutions standard — a solution's deployment guide should follow this provisioning pattern when it offers more than one execution method
- Scripting standard — script parameter contracts, credential resolution order, and logging conventions referenced by the orchestrated and standalone script options
- Documentation standard — baseline documentation requirements, including admonition usage and heading style, that apply to every runbook regardless of platform