Use naming conventions that clearly distinguish placeholders from required identifiers, follow platform identifier constraints, and keep variable scope/semantics correct. - **Placeholders:** If a value is a placeholder, use your docs’ standard placeholder format consistently (e.g., hyphenated: `YOUR-CONNECTION-ID`). - **Required identifiers:** If the name is a real environment variable or action input key, keep it **exactly** as required by the platform/action (do not “normalize” underscores/hyphens). - **Identifier character rules:** Don’t broaden allowed characters in identifiers. If the platform disallows spaces (or you’re defining rules for something that disallows spaces), **do not** permit spaces in examples/specs. - **Scope safety:** Don’t mix GitHub/platform-specific variable documentation with OS/system user-home variables (avoid encouraging edits to or reliance on shell `HOME`). Prefer documenting the platform-provided paths (for example, `GITHUB_WORKSPACE`). - **Semantic accuracy:** Ensure variable names’ descriptions match runtime behavior (don’t swap “model id” vs “wire model/deployment name”). Example (placeholder vs required env var): ```yaml - name: Sign in with OIDC uses: docker/login-action@ with: username: YOUR-DOCKER-ORG # placeholder formatting env: DOCKERHUB_OIDC_CONNECTIONID: YOUR-CONNECTION-ID # required env var name kept exact ```