diff --git a/.expeditor/config.yml b/.expeditor/config.yml index 7c590738a1..e48a3eda51 100644 --- a/.expeditor/config.yml +++ b/.expeditor/config.yml @@ -16,7 +16,7 @@ pipelines: subscriptions: # This will update version of the Chef product Hugo module - # that is used to build the docs when that product is promoted to stable. + # that's used to build the docs when that product is promoted to stable. - workload: artifact_published:stable:chef-workstation:* actions: - bash:.expeditor/update_hugo_modules_artifact_published.sh @@ -29,9 +29,9 @@ subscriptions: - workload: chef/automate:main_completed:project_promoted:chef/automate:main:acceptance:* actions: - bash:.expeditor/update_hugo_modules_project_promoted.sh - - workload: habitat-sh/habitat:main_completed:project_promoted:habitat-sh/habitat:main:current:* - actions: - - bash:.expeditor/update_hugo_modules_project_promoted.sh + # - workload: habitat-sh/habitat:main_completed:project_promoted:habitat-sh/habitat:main:current:* + # actions: + # - bash:.expeditor/update_hugo_modules_project_promoted.sh - workload: pull_request_merged:chef/effortless:main:* actions: - bash:.expeditor/update_hugo_modules_pull_request_merged.sh: diff --git a/.expeditor/update_hugo_modules_project_promoted.sh b/.expeditor/update_hugo_modules_project_promoted.sh index f5be6460e1..9237d0213d 100644 --- a/.expeditor/update_hugo_modules_project_promoted.sh +++ b/.expeditor/update_hugo_modules_project_promoted.sh @@ -1,34 +1,38 @@ #!/bin/bash -set -eoux pipefail +set -euo pipefail +set -x # different chef product repos have their documentation in different subdirectories # this variable has to be defined so we can copy content from the proper subdirectory # that contains the docs content and properly execute the `hugo mod get` command. -if [[ "${EXPEDITOR_PROJECT}" == *"automate"* ]]; then - org="chef" - product_key="automate" - subdirectory="components/docs-chef-io" - manifest="https://packages.chef.io/files/${EXPEDITOR_TARGET_CHANNEL}/automate/latest/manifest_semver.json" - git_sha="$(curl -s $manifest | jq -r -c ".git_sha")" -elif [[ "${EXPEDITOR_PROJECT}" == *"habitat"* ]]; then - org="habitat-sh" - product_key="habitat" - subdirectory="components/docs-chef-io" - manifest="https://packages.chef.io/files/${EXPEDITOR_TARGET_CHANNEL}/habitat/latest/manifest.json" - git_sha="$(curl -s $manifest | jq -r -c ".sha")" - version="$(curl -s $manifest | jq -r -c ".version")" -fi - -branch="expeditor/update_docs_${product_key}_${git_sha}" -git checkout -b "$branch" +case "${EXPEDITOR_PROJECT}" in + *"automate-private"*) + org="chef" + product_key="automate-private" + subdirectory="components/docs-chef-io" + ;; + *"habitat"*) + org="habitat-sh" + product_key="habitat" + subdirectory="components/docs-chef-io" + ;; + *) + echo "Unsupported EXPEDITOR_PROJECT: ${EXPEDITOR_PROJECT}" >&2 + exit 1 + ;; +esac + +timestamp="$(date '+%Y%m%d%H%M%S')" +branch="expeditor/update_docs_${product_key}_${timestamp}" +git checkout -B "$branch" # Update the semver version of the documentation module that chef-web-docs will # use to build the docs from. # See https://gohugo.io/hugo-modules/use-modules/#update-one-module -hugo mod get "github.com/${org}/${product_key}/${subdirectory}@${git_sha}" +hugo mod get "github.com/${org}/${product_key}/${subdirectory}" hugo mod tidy # Update the vendored files in chef-web-docs @@ -38,31 +42,25 @@ hugo mod vendor # Clean the go.sum file -rm go.sum +rm -f go.sum hugo mod clean -### -# Manage Habitat version numbers for release notes -### - -# We use product version numbers for release notes. -# There's no list of Habitat versions on packages.chef.io, so we store one in assets/release-notes/habitat/release-versions.json -# This file is updated every time there's a new release of Hab - -if [[ "${EXPEDITOR_PROJECT}" == *"habitat"* ]]; then - version_data="$(jq --arg version "$version" '. += [$version]' assets/release-notes/habitat/release-versions.json)" && \ - echo -E "${version_data}" > assets/release-notes/habitat/release-versions.json -fi - # submit pull request to chef/chef-web-docs git add . +if git diff --cached --quiet; then + echo "No documentation module updates found for ${product_key}." + git checkout - + git branch -D "$branch" + exit 0 +fi + # give a friendly message for the commit and make sure it's noted for any future # audit of our codebase that no DCO sign-off is needed for this sort of PR since #it contains no intellectual property -dco_safe_git_commit "Bump Hugo module $product_key to latest $EXPEDITOR_TARGET_CHANNEL release ($git_sha)." +dco_safe_git_commit "Bump Hugo module ${product_key} to latest ${EXPEDITOR_TARGET_CHANNEL} release." open_pull_request diff --git a/.github/instructions/doc-types.instructions.md b/.github/instructions/doc-types.instructions.md new file mode 100644 index 0000000000..8a251029ad --- /dev/null +++ b/.github/instructions/doc-types.instructions.md @@ -0,0 +1,395 @@ +--- +description: "Use when asking about doc structure, how to organize a document, or what sections to include. Covers structural templates for tutorials, how-to guides, reference docs, conceptual docs, release notes, and READMEs." +--- + +# Doc type structures + +Source guidance: [The Good Docs Project](https://www.thegooddocsproject.dev/template/) + +--- + +## Tutorial + +**Purpose**: Learning-oriented. The reader follows a guided path and ends with a working result and new skills. Assumes no prior practical knowledge of the tool. Tutorials eliminate unexpected scenarios — engineer the reader toward a successful finish. + +Tutorials differ from how-to guides: tutorials teach; how-to guides guide experienced users through a task. + +```markdown +# + +One paragraph explaining what the reader will build and why it matters to a DevOps engineer. + +## Overview + +### Learning objectives + +By the end of this tutorial, you'll be able to: + +- +- + +### Intended audience + +Who this tutorial is for and what prior knowledge is assumed. + +## Background (optional) + +Any context the reader needs before starting — feature explanation, project structure, key concepts. +Keep this brief; link to conceptual docs for deeper explanations. + +## Before you begin + +- Prerequisite 1 (link to setup steps where applicable) +- Prerequisite 2 + +## Step 1: + +Introductory sentence explaining what this step accomplishes and why. + +1. Step action. Start with an imperative verb. +2. Step action. + + ```shell + # Comment explaining what this command does + command --flag + ``` + + Expected result: describe what the reader should see. + +## Step 2: + +... + +## Summary + +Recap the specific skills and knowledge the reader gained. Don't repeat the learning objectives +word-for-word — describe what they actually built or configured. + +## Clean up (include if tutorial creates persistent or billable resources) + +Steps to remove resources created during the tutorial. + +## Next steps + +- Link to a related how-to guide +- Link to a related conceptual doc or advanced tutorial +``` + +**Guidelines**: +- Tutorials should take 15–60 minutes to complete +- Keep steps to a maximum of 7 primary steps; maximum 4 substeps per step +- Each step builds on the previous one — don't jump ahead +- Show expected output after commands so the reader can verify success +- Use real, working examples — not placeholder logic +- Add comments to all code samples explaining what each part does +- Include a "Clean up" section whenever the tutorial creates persistent or billable resources + +--- + +## How-to guide + +**Purpose**: Task-oriented. Helps an experienced reader complete one specific task or solve one specific problem. Assumes the reader has practical knowledge and knows what they want to achieve. Alerts readers to unexpected scenarios; it doesn't eliminate them the way a tutorial does. + +```markdown +# + +One or two sentences describing the task and when a reader would perform it. +For example: "Use this guide to create a Kubernetes NetworkPolicy that restricts pod-to-pod traffic." + +## Before you begin (include only for non-obvious prerequisites) + +- Prerequisite: tool, permission, or environment needed +- Link to relevant setup docs + +## + +Introductory sentence describing what these steps accomplish. + +1. Step one. Start with an imperative verb. +2. Step two. + + ```shell + # Comment explaining the command + command --flag + ``` + + Expected output or result. + +3. If , do . + +## See also + +- Link to a related how-to guide +- Link to a relevant conceptual doc or reference page +``` + +**Guidelines**: +- One how-to guide covers exactly one task +- Maximum 8–10 steps; if longer, split into multiple guides +- Use conditional imperatives for variations: "If you want X, do Y. To achieve Z, run..." +- Don't explain concepts in the steps — link to conceptual docs instead +- Document only the most common or recommended method; omit or link to alternative methods +- Alert readers to possible unexpected scenarios with `> **Note:**` or `> **Warning:**` admonitions +- Test instructions end-to-end before publishing; re-test after every notable product release + +--- + +## Reference doc + +**Purpose**: Provides accurate, complete technical information designed to be scanned, not read top to bottom. Mirrors the structure of the application or system it documents. Avoid high-level instructions or usage guides — link to how-to guides instead. + +```markdown +# + +One sentence describing what this reference covers. + +## Syntax + +`command [flags] ` + +## Description + +What the command, option set, or configuration does. Keep this concise. + +## Options + +| Flag / Option | Type | Default | Description | +|---------------|------|---------|-------------| +| `--flag` | string | `""` | What it does | +| `--required-flag` | int | required | What it does | + +## Examples + +```shell +# Description of what this example does +command --flag +``` + +```shell +# Description of a second variation +command --flag --other-flag +``` + +## Related + +- Link to related reference page +- Link to related how-to guide +``` + +**Guidelines**: +- Every flag, option, and parameter must be documented; include type and default +- Use `required` in the Default column when there is no default value +- Examples must be present — at least two, showing different configurations +- Use active voice in descriptions: "Returns a JSON object" not "A JSON object is returned" +- Use tables and bulleted lists to maximize scannability +- Maintain consistent structure, terminology, and tone across all reference pages +- Don't include step-by-step procedures — link out to how-to guides + +--- + +## Conceptual doc + +**Purpose**: Helps readers understand a concept, architecture, or system. Provides foundational knowledge so readers can understand how-to guides and reference docs in context. Builds mental models; does not teach by doing. + +Conceptual docs appear early in documentation journeys, or as mid-level layers when a reader encounters an unfamiliar concept in a how-to guide. + +```markdown +# + +(Optional) An introductory paragraph framing the concept's relevance and what the page covers. +Apply the inverted pyramid: start with the high-level idea, then go deeper. + +## What is + +A clear definition scoped to what this document covers. State what is in scope and, where useful, +what is out of scope. Explain how the concept fits into the broader system or workflow. +Use analogies where they help — prefer universally understood comparisons. + +## (Optional) + +If a diagram clarifies the architecture or data flow, describe or embed it here, near the top. + +## (Optional) Background + +Historical context, design decisions, or industry context that affects how the concept works. +Include only if it meaningfully aids understanding. + +## Use cases + +When and why a DevOps engineer would use or encounter this concept. +Frame use cases around the reader's problems: what challenges does this concept solve? + +## (Optional) Comparison + +If the concept has multiple types, versions, or similar alternatives, include a comparison table. + +| | When to use | +|---|-------------| +|