From 7bf735c25a0bb834e1626b6b35ec9f85be511434 Mon Sep 17 00:00:00 2001 From: Sam Irons Date: Mon, 31 Aug 2026 14:54:31 +1000 Subject: [PATCH 1/4] Make this repo the source of truth for docs content standards Add the ten documentation content standards to contributing/standards/, migrated verbatim from the octopus-docs-standards Claude plugin skill. The skill and Confluence copies become pointers to these files, so the standards stop drifting across three locations. Reconciled the one difference between the installed skill copies: the stale ~/.claude/skills copy carried an extra "3 years old or newer" guideline in version-notes.md that the committed plugin version (and the shipped marketplace build) had already dropped. Took the current version. Exclude contributing/standards/** from markdownlint and cspell. CI checks every changed .md file repo-wide, and these files intentionally contain fences without a language, a compact-style example table, and a repeated "Version notes" heading demonstrating two format variants. Linting them would mean editing illustrative content rather than fixing defects. README: add a "Documentation standards" section, and repoint the "Docs page layout guidelines" section at the folder instead of the skill and a Confluence search. CONTRIBUTING: put external contributor instructions before Octopus staff instructions, add a line pointing contributors at the standards before they submit, and replace both INSERT-LINK-HERE placeholders with a Confluence search reference so no broken links ship. Co-Authored-By: Claude Opus 5 (1M context) --- .markdownlint-cli2.jsonc | 2 +- CONTRIBUTING.md | 30 +- README.md | 6 +- contributing/standards/concept-page.md | 264 ++++++++++++++ contributing/standards/concept-topic.md | 177 +++++++++ contributing/standards/content-conventions.md | 100 +++++ contributing/standards/frontmatter.md | 218 +++++++++++ contributing/standards/guide-page.md | 342 ++++++++++++++++++ contributing/standards/reference-page.md | 310 ++++++++++++++++ contributing/standards/reference-topic.md | 235 ++++++++++++ contributing/standards/task-topic.md | 327 +++++++++++++++++ contributing/standards/tutorial-page.md | 310 ++++++++++++++++ contributing/standards/version-notes.md | 123 +++++++ cspell.json | 1 + 14 files changed, 2429 insertions(+), 16 deletions(-) create mode 100644 contributing/standards/concept-page.md create mode 100644 contributing/standards/concept-topic.md create mode 100644 contributing/standards/content-conventions.md create mode 100644 contributing/standards/frontmatter.md create mode 100644 contributing/standards/guide-page.md create mode 100644 contributing/standards/reference-page.md create mode 100644 contributing/standards/reference-topic.md create mode 100644 contributing/standards/task-topic.md create mode 100644 contributing/standards/tutorial-page.md create mode 100644 contributing/standards/version-notes.md diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index 035d938389..d35b766287 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -1,3 +1,3 @@ { - "ignores": ["src/pages/docs/api/**"] + "ignores": ["src/pages/docs/api/**", "contributing/standards/**"] } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d0002c22ff..7b25492851 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,25 @@ # Contributing to the Octopus docs -Contributions to help improve this documentation are welcome. How you contribute depends on whether you're an Octopus staff member or contributing from outside Octopus. +Contributions to help improve this documentation are welcome. How you contribute depends on whether you're contributing from outside Octopus or you're an Octopus staff member. + +Before you submit, check your change against the [documentation content standards](contributing/standards). + +## External contributors + +- The `main` branch has the latest version of the docs. +- Fork this repo and create a branch for your changes. +- Make the changes you'd like to contribute. +- Submit a pull request (PR) to `main` with your changes and include a comment explaining the changes. +- Sign the [Contribution License Agreement (CLA)](https://cla-assistant.io/OctopusDeploy/docs). +- We'll review your PR and accept it or suggest changes. + +See the [Octopus style guide](https://www.octopus.design/latest/brand/writing/overview-VLYeW2mi-VLYeW2mi) for voice, grammar, and formatting conventions. ## Octopus staff Anyone at Octopus can improve the documentation, whether you're fixing a page you found confusing or writing something new. -This section covers the essentials for working directly in this repository. For the complete guide — including a path for drafting content without touching git, current reviewer logistics, and where to get help — see the [Documentation contribution and review guide](INSERT-LINK-HERE). +This section covers the essentials for working directly in this repository. For the complete guide — including a path for drafting content without touching git, current reviewer logistics, and where to get help — search Octopus's internal Confluence instance for "Documentation contribution and review guide". You don't need to know the content standards yourself. The `octopus-docs-standards` and `octopus-writing-guide` skills in Claude Code apply them for you. @@ -48,7 +61,7 @@ Never invent specifics. If a fact isn't confirmed — a version number, an error Put your change on a new branch and open a pull request. Carry your plan into the description so a reviewer can check intent against result. -Review confirms the structure matches the agreed page type, the frontmatter is complete, and no facts were invented or markers left behind — often with the agent's help. The one thing no tool can check is accuracy, so make sure your reviewer has subject-matter expertise for the area you changed. See the [Documentation contribution and review guide](INSERT-LINK-HERE) for who's reviewing during the current documentation uplift. +Review confirms the structure matches the agreed page type, the frontmatter is complete, and no facts were invented or markers left behind — often with the agent's help. The one thing no tool can check is accuracy, so make sure your reviewer has subject-matter expertise for the area you changed. The contribution and review guide in Confluence lists who's reviewing during the current documentation uplift. ### Writing conventions @@ -61,14 +74,3 @@ When you need an example value in docs, use the following: - Fake password: `your-secret-password` In general, prefer "your" over "my". For example, `your-value`. - -## External contributors - -- The `main` branch has the latest version of the docs. -- Fork this repo and create a branch for your changes. -- Make the changes you'd like to contribute. -- Submit a pull request (PR) to `main` with your changes and include a comment explaining the changes. -- Sign the [Contribution License Agreement (CLA)](https://cla-assistant.io/OctopusDeploy/docs). -- We'll review your PR and accept it or suggest changes. - -See the [Octopus style guide](https://www.octopus.design/latest/brand/writing/overview-VLYeW2mi-VLYeW2mi) for voice, grammar, and formatting conventions. diff --git a/README.md b/README.md index c549a96c9b..00513e106b 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,10 @@ See the [Octopus style guide](https://www.octopus.design/latest/brand/writing/ov See [CONTRIBUTING.md](CONTRIBUTING.md) for how to propose a change, whether you're an Octopus staff member using the standards-driven workflow or contributing from outside Octopus. +## Documentation standards + +The content standards that govern how docs pages are structured — page types, topic types, frontmatter, and version notes — live in [contributing/standards](contributing/standards). That folder is the source of truth: the `octopus-docs-standards` Claude Code skill and the internal Confluence guidance both point back to it. + ## Required checks When you raise a pull request, the following checks will take place: @@ -263,7 +267,7 @@ the article column above it. ## Docs page layout guidelines -Page structure, frontmatter, and where version-specific notes belong are governed by the `octopus-docs-standards` skill in Octopus Deploy's built-in Claude Code plugins — see [CONTRIBUTING.md](CONTRIBUTING.md). If you don't use Claude Code (which we recommend), you can find guidance in Octopus's internal Confluence instance. Search for "Documentation standards, guidelines, and templates". The guidance below covers page elements the content standards don't. +Page structure, frontmatter, and where version-specific notes belong are governed by the content standards in [contributing/standards](contributing/standards). The `octopus-docs-standards` skill in Octopus Deploy's built-in Claude Code plugins applies those standards for you — see [CONTRIBUTING.md](CONTRIBUTING.md). The guidance below covers page elements the content standards don't. ### Product screenshots diff --git a/contributing/standards/concept-page.md b/contributing/standards/concept-page.md new file mode 100644 index 0000000000..4b7ef20f66 --- /dev/null +++ b/contributing/standards/concept-page.md @@ -0,0 +1,264 @@ +# Concept page + +A concept page is a content deliverable that helps a reader understand a single, coherent area of Octopus including what its parts are, why they exist, and how they fit together. It composes closely related concept topics into one page, framed by a short introduction and, where useful, supported by reference topics. + +A concept page is for understanding, not for doing. It answers "what is this, and how does it fit?" across a cluster of related concepts. The moment the reader's primary job becomes completing a procedure, the page is a guide page. + +## Concept page elements + +A concept page contains the following elements in order: + +- Frontmatter*, including a title +- Introduction* +- 1 or more concept topics* +- Reference topics +- Related links + +(* = required) + +## Title conventions + +The frontmatter standard governs the title field for any document in the repository and how they should be written. Titles appear as the H1 and the page's `` metadata element, used for SEO and LLM retrieval. + +A concept page title is written differently from a concept topic title. A topic title is a terse noun phrase with no verbs, because it must stay reusable wherever it's embedded. A page title has no such constraint. The page title describes the whole page, not any single topic on it. + +Concept page titles SHOULD be descriptive and written as the page's primary audience would search for it (primary audience is defined in the frontmatter's audience field). + +They MAY use verbs or question framing where that matches how the primary audience searches. + +A well-formed concept page title: + +- How Octopus Deploy works + +Poorly-formed concept page titles: + +- 👋 Hello, Octopus Deploy (too broad — distinguishes nothing) +- Concepts (names the genre of the content, not the subject) + +## Introduction + +**Required** + +The introduction is the opening prose beneath the H1, before the first concept topic. It frames the page, describing what this page covers and why the reader is here. It has no heading of its own. + +The introduction MUST: + +- State what the page covers and orient the reader to the concepts ahead + +The introduction MUST NOT: + +- Define the concepts themselves — that's the job of the concept topics +- Contain a heading + +### Introduction examples + +A well-formed introduction for the page "How Octopus Deploy works": + +> This page explains the main building blocks of Octopus and how they fit together. Once the model makes sense, the rest of the documentation will too, and you'll know where each part of your deployment lives. + +Poorly-formed introductions for the same page: + +> A project is an application you deploy, an environment is where you deploy it, and a release bundles everything needed for one version. (defines the concepts that appear in the page body) + +> Welcome to Octopus! Deployments have never been easier… (adds a heading, includes promotional content, and doesn't orient the reader to what's ahead) + +## Concept topics + +**Required — one or more** + +The body of a concept page is built from concept topics, each authored to the concept topic standard. Every topic's title element renders as an H2 section heading on the page. + +Concept topics MUST: + +- Be closely related. Every topic on the page must belong to the same coherent concept area. +- Each conform to the concept topic standard + +Concept topics MUST NOT: + +- Appear if they don't relate to the others + +### Concept topics examples + +A well-formed set of concept topics for the page "How Octopus Deploy works": + +- Projects, environments, and releases +- The deployment process +- Variables +- Infrastructure +- Lifecycles + +All five related directly to the core deployment model, and each builds on the last. + +A poorly-formed set of concept topics for the same page: + +- Projects, environments, and releases +- The deployment process +- Advanced audit logging +- Octopus REST API authentication + +Advanced audit logging and API authentication don't belong to the core deployment model a new reader is trying to grasp. The page sprawls across unrelated subjects instead of holding one concept area. + +## Reference topics + +**Optional — used sparingly** + +A concept page MAY include reference topics, typically a comparison matrix or a properties table, where enumerated data clarifies a concept the page is explaining. Reference topics are authored to the reference topic standard. + +Reference topics MUST: + +- Support a concept on the page, not stand as the page's purpose +- Each conform to the reference topic standard + +Reference topics MUST NOT: + +- Be the dominant content + +Reference topics SHOULD: + +- Immediately follow the concept topic it supports + +### Reference topic examples + +An acceptable reference topic for the page "How Octopus Deploy works": + +- A "Cloud vs Self-hosted" comparison reference topic placed directly after the concept topic that explains the two hosting models + +Unacceptable reference topics for the same page: + +- Three reference topics containing comparison tables, each introduced by a single sentence (makes lookup and reference the dominant content on the page) +- A "Which hosting option should I choose?" reference topic containing a decision matrix that the rest of the page content is built around (the page now exists to drive a choice making it a guide, not a concept page) + +## Version notes + +**Optional** + +Where the page carries caveats tied to specific self-hosted Octopus versions, collect them in a Version notes block as the last element before Related links. See the version notes standard for what belongs here and how each entry is formed. This element does not appear on pages that have no version-specific caveats. + +## Related links + +**Optional** + +Related links point the reader to where they're likely to go next: how-to pages and guides that put these concepts into use, other concept pages that share context, or reference topics that enumerate options. + +Related links SHOULD: + +- Appear on most concept pages as nearly every page has a sensible next step +- Include the how-to page or guide that operationalizes the concepts + +Related links MUST NOT: + +- Include links that don't resolve +- Exceed five links + +### Related links examples + +A well-formed set of related links for the page "How Octopus Deploy works": + +- Install Octopus Self-hosted +- Deployment targets +- The deployment process +- Variables +- Lifecycles + +A poorly-formed set of related links for the same page: + +- Coming soon: advanced lifecycle configuration (placeholder) +- Links to all eleven pages that mention a deployment (associative rather than navigational, and exceeds the five-link limit) + +## Composition rules + +These rules govern how the topics above are assembled into a page. + +### Scope + +A concept page covers a single coherent concept area. It presents a group of concepts a reader needs to understand together. The topics on the page MUST depend on or directly relate to each other. If a topic stands alone, it belongs somewhere else. + +### Topic order + +Concept topics SHOULD be ordered by dependency. A reader must never reach a topic that assumes one they haven't read yet. Put the most fundamental concept first, then the concepts that build on it. + +Dependency isn't absolute. It's relative to the page's primary audience (defined in the audience field in the page's frontmatter). Order the topics to match how that audience builds understanding toward their job to be done. + +- Do this: Projects, environments, and releases → The deployment process → Variables → Infrastructure → Lifecycles. Each topic builds on the previous one, ordered for an evaluator forming a first mental model of how Octopus works. +- Not this: Lifecycles before releases. A lifecycle governs how a release moves between environments. It's meaningless to a reader who doesn't yet know what a release is. + +### Heading structure + +The heading structure is important for reader scannability and for LLM retrieval. Follow these constraints: + +- The page MUST have exactly one H1: the title, from frontmatter. +- Each concept and reference topic's title renders as an H2. +- A topic MAY use an H3 for an internal subsection where one is genuinely needed. Use sparingly. +- H4 and deeper MUST NOT be used. Content that seems to need an H4 is a signal the topic is doing too much and should be split. + +### Permitted and forbidden topic types + +A concept page MUST contain only concept topics and, optionally, reference topics. + +A concept page MUST NOT contain task, troubleshooting, glossary, or release-note topics: + +- Task topics turn the page into a how-to page or guide. This is the most important boundary on the page. Link to tasks in related links instead of embedding them. +- Troubleshooting, glossary, and release note topics each have their own deliverables. + +## Template + +``` +--- +# Frontmatter — see the frontmatter standard. +# type MUST be: concept +--- +[Introduction. One or two sentences that frame what this page covers and why +the reader is here. No heading.] +## [Concept topic 1 title] +[Concept topic body.] +## [Concept topic 2 title] +[Concept topic body.] +## [Reference topic title] <!-- optional; place immediately after the concept it supports --> +[Reference table.] +## [Concept topic 3 title] +[Concept topic body.] +## Version notes <!-- optional; self-hosted versions only; before Related links --> +## Related links <!-- optional; up to five, no placeholders --> +- [The how-to page or guide that puts these concepts into use] +- [A related concept page] +``` + +## Example + +Here's a short, complete page to use as an example. It contains 2 concept topics explaining Octopus's hosting models, a reference topic that summarizes the differences in a table, and related links that point to related topics that operationalize the content. + +``` +--- +title: How Octopus hosting works +sidebarLabel: Hosting models +description: New to Octopus Deploy? Learn how Octopus Cloud and self-hosted Octopus Server differ so you can understand which fits your team. +type: concept +audience: evaluator +// Other frontmatter is discussed in the frontmatter standard +--- +Octopus runs in two ways: as a managed service we host for you, or as a server +you run yourself. This page explains both models and what changes depending on +which one you use. +## Octopus Cloud +Octopus Cloud is a fully managed instance hosted by Octopus. We run the server, +the database, and the infrastructure behind it, and we handle upgrades, backups, +and availability. You sign in and start building deployment processes — there's +nothing to install or maintain. +## Self-hosted Octopus Server +Self-hosted Octopus Server is an instance you install and run on your own +infrastructure, on-premises or in your own cloud account. You own the database, +the upgrade schedule, and the network boundary. Teams choose self-hosted when +they need Octopus to run inside their own environment for compliance, data +residency, or network-isolation reasons. +## Cloud vs self-hosted +| Responsibility | Octopus Cloud | Self-hosted | +|------------------|-----------------|------------------| +| Hosting | Octopus | You | +| Upgrades | Automatic | You | +| Database | Managed | You | +| Network boundary | Octopus-managed | Your environment | +## Related links +- [Install Octopus Self-hosted](http://path/to/doc) +- [Octopus Cloud](http://path/to/doc) +- [Spaces](http://path/to/doc) +``` diff --git a/contributing/standards/concept-topic.md b/contributing/standards/concept-topic.md new file mode 100644 index 0000000000..4b7f9bb5ca --- /dev/null +++ b/contributing/standards/concept-topic.md @@ -0,0 +1,177 @@ +# Concept topic + +A concept topic explains what something is, why it exists, and how it relates to other parts of the system. Concepts are expository, not procedural. A concept topic answers "what is this?" and "where does it fit?", not "how do I do this?" Concept topics are the primary building block of concept pages and the opening topic in guide pages. + +## Concept topic elements + +Concept topics contain the following elements in order: + +- Title* +- Short description* +- Visual +- Body* + +(* = required) + +## Title + +**Required** + +Write concept page titles as noun phrases using the terms that appear in the product. Titles name the concept. They don't describe an action, ask a question, or frame a learning activity. + +Concept topic titles MUST: + +- Be a noun phrase +- Use the exact canonical term for the concept as it appears in the UI +- Be unique from other topic titles + +Concept topic titles MUST NOT: + +- Contain verbs, gerunds, or question framing +- Exceed 60 characters + +Content topic titles SHOULD NOT be gerund-led. + +### Title examples + +Well-formed titles for concept topics: + +- Deployment targets +- Spaces +- The deployment process + +Poorly-formed titles for concept topics: + +- What is a deployment target? (uses question framing) +- Understanding spaces (uses gerund) +- Configure your deployment process (uses a verb phrase) + +## Short description + +**Required** + +The short description is the opening paragraph of the topic. It defines the concept in plain language and explains why the reader should understand it. + +Concept topic short descriptions MUST: + +- Define the concept +- Include a value statement that explains what understanding this concept enables + +Concept topic short descriptions MUST NOT: + +- Restate the title +- Contain unexplained product-specific terminology + +### Short description examples + +A well-formed short description for concept topics: + +> Deployment targets are the machines and services that Octopus deploys software to. Defining targets lets you control exactly where deployments run and reuse that configuration across projects. + +Poorly-formed short descriptions for concept topics: + +> Deployment targets are targets for deployment. (restates the title, no value statement) + +> Learn everything you need to know about deployment targets. (promotional, defines nothing) + +## Visual + +**Optional** + +Visuals help readers understand concepts and their relationships between components, workflows, or dependencies. A well-placed diagram or screenshot reduces the amount of text a reader needs to understand how something works. They are high-value, optional assets for describing concepts. + +A concept topic may include diagrams or screenshots that clarify the concept. Place each visual immediately after the prose it supports, not in a separate block at the end of the topic. A topic may contain more than one visual. + +Concept topic visuals SHOULD be included when: + +- The concept involves relationships between multiple components +- A hierarchy or flow is central to understanding the concept + +Concept topic visuals MUST: + +- Include alt text describing the image for readers who cannot see it + +Concept topic visuals MUST NOT: + +- Appear without surrounding prose that introduces and interprets what they illustrate + +A visual that's proposed but not yet created or embedded MUST use the SUGGESTED VISUAL marker defined in content-conventions.md, never visible body copy. Once the visual exists, embed it with standard Markdown image syntax and alt text per the MUST rule above — that's what the bracketed notation in this topic's worked examples below represents: an embedded image's placement and alt text, not an unresolved suggestion. + +Want to go further? See the screenshot and diagram standards for guidance on annotation, consistent examples, sizing, and captions. Those standards also contain the guidance LLMs should follow when generating or evaluating visual content in documentation. + +## Body + +**Required** + +The body explains the concept in enough depth for a reader to understand it, apply it correctly, and recognize how it fits into the broader system. + +Concept topic bodies MUST answer: + +- What is this? +- Why does it exist and what does it enable? +- How does it relate to other concepts in the system? + +Concept topic bodies SHOULD answer: + +- When should you use this, and when should you not? + +Concept topic bodies MUST NOT: + +- Contain procedural content, steps, instructions, or UI directions; these belong in a task topic + +### Body examples + +Well-formed body for a concept topic: + +> A deployment target is a machine or service that Octopus deploys software to. Targets represent the infrastructure in your environment — a Windows server running a Tentacle agent, a Linux machine accessible over SSH, a Kubernetes cluster, or a cloud region. Separating targets from the deployment process means you can change where software runs without changing how it deploys. +> +> Deployment targets belong to one or more environments, such as Development, Staging, or Production. Each target is assigned one or more roles — plain text labels like web-server or db-server — that connect it to the steps in a deployment process. A step that targets the role web-server runs against every deployment target carrying that role in the environment being deployed to. +> +> Use a deployment target when you are deploying software to a machine or service. If you need to run scripts or perform operations that aren't tied to a specific machine — such as calling an API or running a database migration — use a worker instead. + +Poorly-formed body for a concept topic: + +> To add a deployment target, go to Infrastructure > Deployment Targets and select Add Target. Select the target type and follow the prompts to complete registration. Once registered, your target will appear in the target list and can be assigned to an environment. + +(This describes how to use the UI, not what a deployment target is. It belongs in a task topic.) + +## Examples + +Here's an example of a well-formed concept topic: + +--- + +**Deployment targets** + +Deployment targets are the machines and services that Octopus deploys software to. Defining targets lets you control exactly where deployments run and reuse that configuration across projects and teams. + +<!-- [Diagram showing the relationship between a deployment target, its environment, its roles, and the deployment process steps that reference those roles.] --> + +A deployment target represents a unit of infrastructure in your environment — a Windows server running a Tentacle agent, a Linux machine accessible over SSH, a Kubernetes cluster, or a cloud region. Separating targets from the deployment process means you can change where software runs without changing how it deploys. A deployment process that works in your Development environment works identically in Production because the process is the same — only the targets differ. + +Deployment targets belong to one or more environments, such as Development, Staging, or Production. Each target is assigned one or more roles — plain text labels like web-server or db-server — that connect it to the steps in a deployment process. A step configured to target the role web-server runs against every deployment target carrying that role in the environment being deployed to. + +Use a deployment target when you are deploying software to a specific machine or service. If you need to run scripts or operations that aren't tied to a specific machine — such as calling an API, sending a notification, or running a database migration — use a worker instead. + +--- + +Here's an example of a poorly-formed concept topic: + +--- + +**What is a deployment target and how do I configure one?** + +Deployment targets are targets that you deploy to in Octopus Deploy. This page will explain everything you need to know about deployment targets and how to use them effectively in your deployment process. + +To add a deployment target, navigate to Infrastructure > Deployment Targets and click Add Target. Select the target type from the list — options include Tentacle (Windows), Tentacle (Linux), SSH Connection, Kubernetes, and Azure Web App. Complete the required fields and click Save. Your new target will appear in the target list. + +[Screenshot of the Add Deployment Target screen.] + +--- + +Why is this poorly-formed? + +- The title uses question framing and verb phrase combined and exceeds 60 characters. +- The short description restates the title. It contains no value statement and uses promotional framing ("everything you need to know"). It also contains unexplained terms ("deployment process") without context. +- The body content is procedural. It describes UI navigation and steps. It does not explain what a deployment target is, why it exists, or how it relates to other parts of the system. +- The visual appears without any surrounding prose to introduce or interpret it. A reader arriving at this image has no context for what they're looking at. diff --git a/contributing/standards/content-conventions.md b/contributing/standards/content-conventions.md new file mode 100644 index 0000000000..219c188c38 --- /dev/null +++ b/contributing/standards/content-conventions.md @@ -0,0 +1,100 @@ +# Content conventions + +This standard governs authoring conventions that apply across every topic and page type: output format, the markers used for not-yet-real content, and how a proposed visual is represented before it exists. It is a cross-cutting standard, like `frontmatter.md`: it sits alongside, not inside, the page and topic standards that govern body content, and it applies regardless of deliverable type. + +This standard does not define page structure, topic elements, or frontmatter fields; those belong to the relevant page, topic, and frontmatter standards. + +## Output format + +Deliverables MUST be authored in Markdown (`.md`) by default. + +MDX (`.mdx`) SHOULD be used only when a page needs components that Markdown cannot express — for example, an interactive tabbed code sample or an embedded UI widget. Plain prose, headings, lists, tables, and images do not qualify; Markdown expresses all of them on its own. + +### Output format examples + +- Do this: author `deployment-targets.md` as plain Markdown, since headings, a table, and prose fully express the content. +- Not this: author the same content as `deployment-targets.mdx` because MDX happens to be available. Reaching for MDX without a genuine component need adds a build dependency the page doesn't use. + +## Authoring markers (pre-ship, tracked, greppable) + +Content isn't always ready to ship the moment it's drafted. Authoring markers name what's missing so the gap is visible, greppable, and owned — never silently invented, and never silently shipped. A marker is a pre-publication authoring artifact. It is never rendered to readers and must not survive into a shipped page. + +**Disambiguation.** This is a different concept from the "no placeholders" rule that governs related links elsewhere in these standards (see concept-page.md, guide-page.md, reference-page.md). That rule prohibits a shipped dead end — a "Coming soon" link that never resolves — and it remains forbidden, unchanged. The markers defined here are the opposite case: a pre-ship signal that a human still needs to act, which must be resolved or removed before the page can pass. The word "placeholder" appears in both rules; they are not the same rule, and must not be conflated. + +Three markers cover the ways content can be not-yet-real. Each is typed: it carries its specifics inline rather than standing as a bare token. + +| Marker | Form | Means | +|---|---|---| +| `[VERIFY: <claim> — needs: <what/who confirms it>]` | Bracket tag | Content is present but not yet confirmed against source. | +| `[PLACEHOLDER: <what is missing> — needs: <what a human must supply>]` | Bracket tag | Content is absent. | +| `<!-- SUGGESTED VISUAL: <what to show and why> -->` | HTML comment | A visual is proposed but not yet created or embedded. | + +The suggested-visual marker uses an HTML comment rather than a bracket tag because it stands in for a block element (an image or diagram) and MUST NOT render to readers the way inline bracketed prose would. + +Authoring markers MUST: + +- Match one of the three forms above exactly, so every marker in a page or across the repository can be found with a single grep pattern. +- State what is missing or unconfirmed, and what a human must supply to resolve it, inline in the marker itself. A bare token (`[TODO]`, `[PLACEHOLDER]` with nothing after it) carries neither and is not well-formed. +- Be used, by human or AI authors alike, in place of inventing a technical specific. A fabricated flag, setting, or path is the highest-severity defect in these standards — worse than a marked gap, because a reader acts on it as if it were confirmed. + +Authoring markers MAY: + +- Exist in in-progress content. A gap never halts the work (flag forward); mark it and keep moving. + +A page carrying an unresolved marker MUST NOT be considered conformant or shippable. Markers are resolved — grounded in source — or removed entirely before a page passes validation. A page with zero markers is, on this axis, shippable; a page with any unresolved marker is not. + +### Authoring markers examples + +- Do this: `[PLACEHOLDER: the minimum supported Kubernetes version — needs: confirmation from the Kubernetes step SME]` +- Not this: inventing "Kubernetes 1.24 or later" to fill the gap, or leaving a bare `[TODO]` with no detail + +A well-formed draft fragment carrying markers: + +> Tentacle requires **[VERIFY: minimum supported .NET runtime version — needs: confirmation from the Tentacle release notes]** on the target machine. +> +> [PLACEHOLDER: the error message shown when a health check times out — needs: the exact string or a screenshot from engineering] +> +> <!-- SUGGESTED VISUAL: a sequence diagram showing the health check handshake between Server and Tentacle --> + +This is well-formed because each marker states exactly what's missing and what resolves it, matches one of the three forms exactly, and the suggested visual is a comment — invisible if the page shipped exactly as drafted. + +A poorly-formed version of the same fragment: + +> Tentacle requires .NET 6.0 or later on the target machine. If the health check fails, you'll see a timeout error. +> +> [Insert diagram of the health check handshake here] + +This is poorly-formed because the .NET version and the error message are invented rather than marked — the highest-severity defect — and the visual is written as visible body copy instead of a comment. A reader would see "[Insert diagram of the health check handshake here]" rendered on the live page. + +## Suggested visuals + +This section states when the SUGGESTED VISUAL marker (defined above) applies. It does not redefine topic-level visual rules — see concept-topic.md (## Visual) and task-topic.md (### Inline screenshots in steps) for when a visual should be included and what it must contain. + +A visual that is proposed but not yet created or embedded MUST be written as the `<!-- SUGGESTED VISUAL: <what to show and why> -->` comment, never as visible body copy. + +An actual, created visual MUST use normal Markdown image syntax with alt text (`![alt text](path)`), per the visual rules in the relevant topic standard. + +An "insert screenshot here"-style note MUST NOT appear as rendered body copy, in any form — bracketed, bolded, or plain prose. + +### Suggested visuals examples + +- Do this: `<!-- SUGGESTED VISUAL: a diagram showing the relationship between a deployment target, its environment, and its roles -->` +- Not this: `[Insert a diagram here showing the relationship between a deployment target, its environment, and its roles]` written as visible prose in the topic body + +A well-formed treatment of a proposed visual, mid-draft: + +> Deployment targets belong to one or more environments and carry roles that connect them to deployment process steps. +> +> <!-- SUGGESTED VISUAL: a diagram showing a deployment target linked to an environment and the roles that connect it to process steps --> +> +> Use a deployment target when deploying to a specific machine or service. + +A poorly-formed treatment of the same: + +> Deployment targets belong to one or more environments and carry roles that connect them to deployment process steps. +> +> [Insert diagram here] +> +> Use a deployment target when deploying to a specific machine or service. + +This is poorly-formed because "[Insert diagram here]" is written as visible body copy. A reader arriving at the shipped page would see the literal bracketed text rendered where a diagram should be. diff --git a/contributing/standards/frontmatter.md b/contributing/standards/frontmatter.md new file mode 100644 index 0000000000..a9e4a3c40a --- /dev/null +++ b/contributing/standards/frontmatter.md @@ -0,0 +1,218 @@ +# Frontmatter + +This standard governs the YAML frontmatter block at the top of every page deliverable. It is a cross-cutting standard: it applies to all deliverable types (concept pages, guide pages, reference pages, and the deliverables that follow as their standards ship). It sits alongside, not inside, the page and topic standards that govern body content. + +This standard defines which fields exist, the rules for each field, the build-time values derived from frontmatter, and what the validation check enforces. It does not govern body content, topic structure, or title conventions beyond the page title; those belong to the relevant page and topic standards. + +## The schema + +Every page MUST carry the following frontmatter block. The schema is a fixed skeleton: every defined field is present in every file, including optional ones. + +- The frontmatter block MUST contain every field defined in this schema. +- Required fields MUST be non-empty. +- Optional fields MUST be present but MAY be empty. An empty value parses as null and is treated as "not provided". + +| Field | Required | Type | Constraint | Purpose | +|---|---|---|---|---| +| `title` | Required | string | ≤ 60 chars | Renders as the page H1 and `<title>`. Follows the deliverable's page standard for title convention. | +| `sidebarLabel` | Required | string | short; distinct within its nav group | Navigation label. | +| `navOrder` | Optional | integer | — | Sibling order within the nav group. Empty accepts default ordering. | +| `description` | Required | string | ≤ 160 chars | Meta description. Not rendered in the page body. | +| `subject` | Optional | string | comma-separated; 2–8 keywords recommended; no duplicates | Keywords for search faceting and GEO. Optional but highly recommended. | +| `type` | Required | enum | one of concept, guide, reference, tutorial | Internal deliverable type. Drives @type and layout by mapping (see Mapping tables). | +| `audience` | Required | enum list | one or more values from the controlled vocabulary | Declared target audience. Multi-valued. Also seeds the synthetic-persona review step. | +| `image` | Optional | string (path) | resolves to an existing file when set | Open Graph share image. Empty falls back to the site default. | +| `imageAlt` | Conditional | string | required and non-empty when image is set | Alt text for the OG image. | + +## Field-by-field rules + +### title + +The title field MUST: + +- Be present and non-empty +- Be ≤ 60 characters +- Follow the title convention of the deliverable's page standard. This is the page title (H1), not a topic title; topic-level title rules DO NOT apply here. + +The title field MUST NOT contain Markdown, HTML, or trailing punctuation. + +- Do this: `Manage deployment targets` +- Not this: `Adding, configuring, and removing your Octopus deployment targets` (over 60 characters; task-topic phrasing; reads as a list of topics, not a page) + +The title's format is set by the deliverable's page standard and varies by type, so the same feature yields different page titles: a guide page uses a gerund ("Managing deployment targets"), while concept and reference pages use noun phrases ("Deployment targets," "System variables"). Always check the deliverable's page standard for the exact convention. + +### sidebarLabel + +The sidebar label field MUST: + +- Be present and non-empty + +The sidebar label field SHOULD: + +- Be unique among siblings in the same nav group +- Be shorter than title + +The sidebar label field MAY: + +- Equal title when title is already short and unambiguous in a list. + +### navOrder + +navOrder MAY be empty. When non-empty, it MUST be an integer. Empty means the nav applies its default ordering. + +### description + +The description field MUST: + +- Be present and non-empty +- Be ≤ 160 characters + +The description field SHOULD: + +- Be unique per page + +Descriptions are not rendered in the page body. They populate meta descriptions only. Reused descriptions weaken search differentiation, hence they should be unique-per-page. + +### subject + +The subject field is optional but highly recommended. It MAY be empty. + +When non-empty, the subject field MUST be formatted as a comma-separated list of 2–8 keywords. These keywords should be unique (no duplicates; case-insensitive). + +The subject field feeds DC.subject (Dublin Core) and keywords (schema.org) for search faceting and GEO. One lazy keyword helps nothing. + +- Do this: `deployment targets, Tentacle, SSH, Kubernetes, deployment infrastructure` +- Not this: `deployment targets` (below the useful floor) / `Kubernetes, kubernetes` (duplicate) + +### type + +The type field MUST: + +- Be present and non-empty +- Be exactly one of: concept, guide, reference, or tutorial. + +The type is the page's single source of truth for what the deliverable is, defining both schema.org metadata blocks and the supported page layout when the site builds. See "Mapping tables" below for more details. + +### audience + +The audience field MUST: + +- Be present, with one or more values from the vocabulary table that follows. + +The audience field MUST NOT: + +- Contain values outside the list. A new audience value requires a change to this standard. + +The audience field MAY: + +- Be multi-valued. + +Valid audience values are kebab-case, all-lowercase, and drawn from this list: + +| Value | Meaning | +|---|---| +| `app-dev` | Application developer | +| `devops-eng` | DevOps engineer | +| `platform-eng` | Platform engineer | +| `infra-eng` | Infrastructure engineer | +| `admin` | Octopus administrator | +| `buyer` | Purchasing or decision-making stakeholder | +| `evaluator` | Assessing the product, not yet adopted | +| `new-user` | Recently adopted, still onboarding | +| `power-user` | Experienced, proficient user | + +The values group loosely into role (`app-dev`…`buyer`), journey stage (`evaluator`, `new-user`), and proficiency (`power-user`). Any combination is valid. + +- Do this: `[evaluator, new-user]` +- Not this: `[developers, beginners]` (free-form values outside the vocabulary) + +### image + +The image field is optional and MAY be empty. When non-empty, the image field MUST be a path that resolves to an existing file in the repository. + +Most pages set no custom share image and fall back to the site default. Empty is the normal state. + +### imageAlt + +MUST be present and non-empty when image is non-empty. + +When image is empty, imageAlt MUST be present but empty. + +When there is no image, the key still exists (skeleton convention) but carries nothing. + +## Mapping tables + +@type and layout are derived from type at build time. Neither is stored in frontmatter. + +The build MUST derive @type and layout from type using the tables below. A type value with no row is a build error, not a silent fallback. + +type → schema.org @type (emitted in the JSON-LD block): + +| type | @type | +|---|---| +| concept | TechArticle | +| guide | TechArticle | +| reference | TechArticle | +| tutorial | TechArticle | + +type → layout (the Astro layout component): + +| type | layout | +|---|---| +| concept | article | +| guide | article | +| reference | article | +| tutorial | article | + +## Examples + +Here's an example of a well-formed frontmatter block with every defined field present, and optional fields left empty where unused: + +```yaml +--- +title: Managing deployment targets +sidebarLabel: Deployment targets +navOrder: 3 +description: Add, configure, and remove the machines and services Octopus deploys to. +subject: deployment targets, Tentacle, SSH, Kubernetes, deployment infrastructure +type: guide +audience: [platform-eng, infra-eng, new-user] +image: +imageAlt: +--- +``` + +This is well-formed because: + +- title is feature-scoped, under 60 chars with no trailing punctuation +- sidebarLabel is shorter than the title and reads cleanly in a narrow nav column +- navOrder is set because position relative to siblings matters +- description is one plain-prose sentence under 160 chars +- subject is a comma-separated list of five keywords within the 2–8 band with no duplicates +- type is guide which is a valid value according to the table in this spec +- audience contains three valid values from the vocabulary +- image and imageAlt are both present but remain empty (which falls back to the default Open Graph image at build time) + +Here's an example of a poorly-formed frontmatter block: + +```yaml +--- +title: Adding, configuring, viewing, and deleting your deployment targets in Octopus +description: Deployment targets. +subject: deployment targets +type: how-to +audience: [developers, beginners] +image: /img/targets-og.png +imageAlt: +--- +``` + +This is poorly-formed because: + +- title is over the character limit and styled as a task list rather than a page title +- description is too thin for humans or machines to reasonably predict the content present on the page +- subject keyword list does not contain enough keywords to help facilitate search +- type uses a token that does not exist +- audience carries free-form values that are not valid according to this spec +- image is set while imageAlt is empty, the one invalid combination of that pair +- The block is also missing the sidebarLabel and navOrder fields diff --git a/contributing/standards/guide-page.md b/contributing/standards/guide-page.md new file mode 100644 index 0000000000..e1a65bacdf --- /dev/null +++ b/contributing/standards/guide-page.md @@ -0,0 +1,342 @@ +# Guide page + +A guide page is a content deliverable that helps a reader accomplish a feature-scoped job in Octopus. It composes one or more task topics into a single page, framed by a short introduction and optionally supported by concept and reference topics. + +A guide page is for doing, not for understanding. It answers "how do I accomplish this?" for one coherent feature. The moment the reader's primary job becomes understanding what something is or how it fits, rather than completing a procedure, the page is a concept page. + +## Guide page elements + +A guide page contains the following elements in order: + +- Frontmatter*, including a title +- Introduction* +- Concept topics +- 1 or more task topics* +- Reference topics +- Related links + +(* = required) + +## Title conventions + +The frontmatter standard governs the title field for any document in the repository. Titles appear as the H1 and the page's `<title>` metadata element, used for SEO and LLM retrieval. + +A guide page title is scoped to the page's job — the feature or the end-to-end journey the page covers as a whole — not to any single task on it. + +Guide page titles MUST: + +- Be a gerund phrase ("Managing deployment targets"), not imperative ("Manage deployment targets") +- Name the page's overall job, not one task on it +- Be 60 characters or fewer + +Guide page titles SHOULD: + +- Use a verb that encompasses the page's task set + +A well-formed guide page title: + +- Managing deployment targets + +Poorly-formed guide page titles: + +- Manage deployment targets (imperative; reserved for task topic titles) +- Deployment targets (noun-only; collides with the concept page for the same feature) +- Add a deployment target (scoped to one task, not the page) + +## Introduction + +**Required** + +The introduction is the opening prose beneath the H1, before the first topic. It frames what the reader can accomplish on this page and orients them to the work ahead. It has no heading of its own. + +The introduction MUST: + +- State what the page lets the reader accomplish and orient them to the tasks ahead + +The introduction MUST NOT: + +- Contain procedure steps — that's the job of the task topics +- Teach the concepts in depth — that's the job of a concept topic or a concept page +- Contain a heading + +### Introduction examples + +A well-formed introduction for the guide "Managing deployment targets": + +> A deployment target is the machine or service Octopus deploys to. This page covers registering targets, configuring them with roles, and removing them when they're no longer in use. + +Poorly-formed introductions for the same page: + +> To register a target, go to Infrastructure > Deployment Targets > Add Deployment Target and select a target type. (contains procedure steps that belong in a task topic) + +> Deployment targets can be tagged with target tags, which map to deployment steps via roles. A single tag can be referenced by many projects, so changing one affects every process that depends on it. (teaches the concept model in depth instead of orienting; this belongs in a concept topic or concept page) + +## Concept topics + +**Optional** + +A guide page MAY include concept topics, each authored to the concept topic standard, where the reader needs a model the introduction can't carry in a line or two. Each renders as an H2. + +A feature guide rarely needs more than one. A journey guide — one covering an end-to-end configuration rather than a single feature — may need several, introduced at the point in the sequence where each becomes relevant. How they're ordered against the tasks they inform is governed by topic order in the composition rules below. + +Concept topics MUST: + +- Establish only the model the tasks on this page need +- Each conform to the concept topic standard + +Concept topics MUST NOT: + +- Duplicate framing already carried by the introduction +- Become the page's primary content — if understanding is the reader's main job, the page is a concept page + +### Concept topic examples + +An acceptable concept topic for the page "Managing deployment targets": + +- A single "Deployment targets and roles" concept topic, placed before the task topics, establishing the target/role/tag model the tasks rely on. + +Unacceptable concept topics for the same page: + +- Four concept topics covering target types, roles, tags, and health checks, with the task topics pushed to the bottom of the page (understanding is now the page's primary job; this is a concept page with procedures bolted on) +- A "How deployment targets work" concept topic that re-explains the target model the introduction already framed (duplicates the introduction; the topic should add the model the intro can't carry, not restate it) + +## Task topics + +**Required — one or more** + +The body of a guide page is built from task topics. Every topic's title element renders as an H2. + +Task topics MUST: + +- Each conform to the task topic standard +- Belong to the same page-level job as the other tasks on the page + +Task topics MUST NOT: + +- Appear if they belong to a different feature or journey than the rest of the page + +### When an operation earns its own task topic + +Not every operation a feature supports deserves a task topic. CRUD operations are common (add, configure, view, delete), and the trivial ones produce thin, fabrication-prone topics when forced into the task structure. + +An operation earns its own task topic when it has either: + +- More than one non-obvious step, or +- A material prerequisite or consequence the reader must know + +An operation that has neither MUST be folded into the concept or reference topic that documents the entity or as a closing step of the task it naturally completes. + +For example: Does the task of deleting a deployment target earn its own task topic? The procedure is trivial and obvious, but deleting a target that projects still deploy to has consequences the reader should know before acting. So, yes, it should get its own topic. The actionable consequences (what breaks, what to check first) belongs in the task topic alongside the procedure for deleting. The underlying model of why targets, roles, and tags interrelate belongs in a concept topic. + +Another example: Does the task of viewing a deployment target earn its own task topic? The procedure is trivial and obvious. It is a single navigation step without prerequisites and self-evident result. So, no, it does not earn its own topic. Fold it into the concept topic that documents what a deployment target is, instead. + +### Task topic examples + +A well-formed set of task topics for the page "Managing deployment targets": + +- Add a deployment target +- Configure target roles +- Delete a deployment target + +Each is a distinct operation on the same feature. Add and configure operations involve more than one step, so they earn their own topic. The delete operation involves a material consequence, earning its own topic. The view operation is absent, folded into the concept topic that explains what a deployment target is. + +A poorly-formed set of task topics for the same page: + +- Add a deployment target +- View a deployment target +- Understanding target roles +- Troubleshoot target registration + +View is a single self-evident step and earns no topic. "Understanding target roles" is a concept topic wearing a task topic title. It teaches a model rather than completing an operation. "Troubleshoot target registration" is a troubleshooting topic, which is never assembled into a guide. These live as their own deliverables, linked from the relevant task's troubleshooting element. + +## Reference topics + +**Optional — used sparingly** + +A guide page MAY include reference topics where enumerated data supports a task on the page, for example a table of target types, a properties reference, or a permissions matrix. + +Reference topics MUST: + +- Support a task on the page, not stand as the page's purpose +- Each conform to the reference topic standard + +Reference topics MUST NOT: + +- Be the page's dominant content + +Reference topics SHOULD: + +- Immediately follow the task they support + +### Reference topic examples + +An acceptable reference topic for the page "Managing deployment targets": + +- A "Target types" reference table placed directly after the task that registers a target, enumerating the target types the user can choose from. + +An unacceptable reference topic for the same page: + +- A "Deployment target settings" reference table the whole page is built around, with the task topics reduced to a sentence each. (lookup is now the page's purpose) + +## Version notes + +**Optional** + +Where the page carries caveats tied to specific self-hosted Octopus versions, collect them in a Version notes block as the last element before Related links. See the version notes standard for what belongs here and how each entry is formed. This element does not appear on pages that have no version-specific caveats. + +## Related links + +**Optional** + +Related links point the reader to where they're likely to go next: the concept page that explains the feature this guide operates, other guides for adjacent features or journeys, or reference pages that enumerate options. + +Related links are a page-level element, distinct from the links inside a task topic. A task topic carries its own links for recovery (the troubleshooting element) and for forward motion (the next steps element). Related links are neither: they serve lateral discovery, where the reader goes after the page's job is done, not mid-task. + +Related links SHOULD: + +- Appear on most guide pages, as nearly every page has a sensible next destination +- Include the concept page that explains the feature, where one exists + +Related links MUST NOT: + +- Include links that don't resolve +- Exceed five links + +### Related links examples + +A well-formed set of related links for the page "Managing deployment targets": + +- How deployment targets work +- Deploying to Kubernetes +- Environments +- Roles and target tags + +A poorly-formed set of related links for the same page: + +- Coming soon: dynamic target discovery (placeholder that doesn't resolve) +- Links to all fourteen pages that mention a deployment target (associative rather than navigational and exceeds the five-link limit) + +## Composition rules + +These rules govern how the topics above are assembled into a page. + +### Scope + +A guide page covers a single page-level job: one feature, or one end-to-end journey. Every task topic on the page MUST serve that job. A reader who lands on the page to do one thing should find the tasks that thing requires, and not tasks that belong to a different feature or journey. + +Scope is set by the page's job, not by a feature boundary. A guide's scope may be at the feature level ("Managing deployment targets"). Or, it may be at the journey level ("Deploying to Kubernetes"). Guides that describe journeys may cross several features — targets, environments, deployment processes — because the journey needs them, held together by the reader's goal rather than by a single feature. + +#### Examples of scope + +Acceptable scopes for a guide: + +- A "Managing deployment targets" page that contains add, configure, and delete tasks. Every task operates the same feature. +- A "Deploying to Kubernetes" page that contains tasks that register a Kubernetes target, add a deployment step, and create a release. These are different features held together by the single goal of getting a deployment running on a Kubernetes cluster. + +Unacceptable scope for a guide: + +- A "Managing deployment targets" page that also contains "Create an environment." Environments are a different feature and should have their own feature-level guide page. + +### Topic order + +Topics on a guide page follow the order the reader works in. A reader must never reach a task that depends on one they haven't done yet, or that assumes a model the page hasn't given them. + +Order is relative to the page's primary audience, defined in the audience field in the page's frontmatter. Order the topics to match how that audience works toward the job the page delivers. + +A concept topic MUST precede the tasks that depend on the model it establishes. On a feature guide, this usually means a single concept topic at the top, ahead of all the tasks. On a journey guide, concept topics are placed at the point in the sequence where each becomes relevant, not all models front-loaded before any work begins. + +A reference topic SHOULD immediately follow the task it supports, so the reader meets the enumerated data at the moment the task calls for it. + +- Do this: On "Managing deployment targets," order the tasks add → configure → delete, with the "Target types" reference topic immediately after add. You must add a target first, looking up which type to be successful, before you can configure the target. And you must configure the target before its deletion has consequences worth warning about. +- Do this: On "Deploying to Kubernetes," introduce the target/role model, register the target, then introduce the release model, then create the release. Each concept lands just before the tasks that rely on it. +- Not this: On "Deploying to Kubernetes," front-load both concept topics at the top, then all tasks. The reader has to hold the release model in their head through three unrelated registration tasks before it's used. + +### Heading structure + +The heading structure is important for reader scannability and for LLM retrieval. Follow these constraints: + +- The page MUST have exactly one H1: the title, from frontmatter. +- Each concept, task, and reference topic's title renders as an H2. +- A topic MAY use an H3 for an internal subsection where one is genuinely needed. Use sparingly. +- H4 and deeper MUST NOT be used. Content that seems to need an H4 is a signal the topic is doing too much and should be split. + +### Permitted and forbidden topic types + +A guide page MUST contain only task topics and, optionally, concept and reference topics. + +A guide page MUST NOT contain troubleshooting, glossary, or release-note topics: + +- Troubleshooting topics are never assembled into a guide. A troubleshooting topic is its own deliverable with its own URL, linked from the Troubleshooting element of the task it relates to — not embedded in the page and not collected in a page footer. This keeps recovery content addressable on its own and lets one troubleshooting topic serve tasks across several guides. +- Glossary and release-note topics each have their own deliverables. + +## Template + +``` +--- +# Frontmatter — see the frontmatter standard. +# type MUST be: guide +--- +[Introduction. One or two sentences framing what the reader can accomplish +on this page and the tasks ahead. No heading.] +## [Concept topic title] <!-- optional; the model the tasks need --> +[Concept topic body.] +## [Task topic 1 title] <!-- imperative: "Add a deployment target" --> +[Task topic body.] +## [Reference topic title] <!-- optional; place immediately after the task it supports --> +[Reference table.] +## [Task topic 2 title] +[Task topic body.] +## [Task topic 3 title] +[Task topic body.] +## Version notes <!-- optional; self-hosted versions only; before Related links --> +## Related links <!-- optional; up to five, no placeholders --> +- [The concept page that explains this feature] +- [An adjacent guide] +``` + +## Example + +Here's a short, complete guide page to use as an example. It opens with a concept topic establishing the target/role model, then documents 3 task topics (add, configure, delete), with a "Target types" reference table placed immediately after the task that needs it. + +``` +--- +title: Managing deployment targets +sidebarLabel: Deployment targets +description: Add, configure, and remove the machines and services Octopus deploys to. +type: guide +audience: devops-eng +// Other frontmatter is discussed in the frontmatter standard +--- +A deployment target is the machine or service Octopus deploys to. This page +covers registering targets, giving them roles so deployment steps know where to +run, and removing them safely when they're no longer in use. +## Deployment targets and roles +A deployment target represents somewhere Octopus deploys to — a virtual machine, +a Kubernetes cluster, a cloud service. A role is a tag you assign to a target so +that deployment steps can select it by role rather than by name. One role can +apply to many targets, and one target can carry many roles. You can view a +target's current roles on its detail page under Infrastructure ▸ Deployment +Targets. +## Add a deployment target +[Task topic body, authored to the task topic standard: prerequisites, steps, +and a Result confirming the target appears as healthy.] +## Target types +| Target type | Use it for | +|--------------------|---------------------------------------------| +| Listening Tentacle | Windows/Linux machines Octopus connects to | +| Polling Tentacle | Machines behind a firewall that call home | +| Kubernetes cluster | Deployments to a Kubernetes API | +| Azure Web App | Deployments to an Azure App Service | +## Configure target roles +[Task topic body: how to assign and change roles on an existing target, with a +Result confirming the role appears on the target.] +## Delete a deployment target +[Task topic body: the delete procedure, preceded by the consequence the reader +must know — deleting a target that projects still deploy to will break those +deployments — and how to check what depends on it first. Links to "Deployment +targets and roles" for why the dependency exists.] +## Related links +- [How deployment targets work](http://path/to/doc) +- [Deploying to Kubernetes](http://path/to/doc) +- [Environments](http://path/to/doc) +``` diff --git a/contributing/standards/reference-page.md b/contributing/standards/reference-page.md new file mode 100644 index 0000000000..6e01a8329b --- /dev/null +++ b/contributing/standards/reference-page.md @@ -0,0 +1,310 @@ +# Reference page + +A reference page is a content deliverable that helps a reader look up a complete set of values, options, settings, or commands. It composes one or more reference topics into a single page, framed by a short introduction. + +A reference page is for looking up, not for understanding or doing. It answers "what values exist, and what does each one do?" across one or more related sets. The moment the reader's primary job becomes understanding a model (how the parts fit and why), the page is a concept page. The moment it becomes completing a procedure, the page is a guide page. + +## Reference page elements + +A reference page contains the following elements in order: + +- Frontmatter*, including a title +- Introduction* +- 1 or more reference topics* +- Related links + +(* = required) + +## Title conventions + +The frontmatter standard governs the title field for any document in the repository and how they should be written. Titles appear as the H1 and the page's `<title>` metadata element, used for SEO and LLM retrieval. + +A reference page title is written like a reference topic title. Both are noun phrases naming an enumerated set. The difference is scope, not form. A reference topic title names the single set enumerated in that topic and must be unique among the topics on the page. A reference page title names the page's whole subject, which may span several related sets. + +Reference page titles MUST: + +- Be a noun phrase naming the set(s) the page enumerates +- Use the canonical product term as it appears in the UI or artifact +- Be 60 characters or fewer + +Reference page titles MUST NOT: + +- Be a gerund phrase +- Use imperative verbs or question framing + +Well-formed reference page titles: + +- System variables +- Variable filters +- Built-in user roles + +Poorly-formed reference page titles: + +- Managing system variables (gerund, signals a guide page not a reference page) +- Configure variable filters (imperative, signals a task topic) +- What variables can I use (question framing) + +## Introduction + +**Required** + +The introduction is the opening prose beneath the H1, before the first reference topic. It frames the page, describing what the page enumerates and orienting the reader to the sets ahead. It has no heading of its own. + +The introduction MUST: + +- State what the page enumerates and orient the reader to the sets ahead +- Carry any caveat that applies across all topics on the page, such as version scope, "all values are strings," or partial-set warnings that span topics. + +The introduction MUST NOT: + +- Begin enumerating individual entries +- Explain a model or teach why the sets matter +- Contain procedure steps +- Contain a heading + +### Introduction examples + +A well-formed introduction for the page "System variables": + +> This page lists the built-in variables Octopus provides for use in deployment processes, runbooks, and custom scripts. Variables are grouped by the scope they're drawn from. All Octopus variables are strings, even when the value looks like a number or boolean. + +Poorly-formed introductions for the same page: + +> Octopus.Release.Id returns the ID of the release; Octopus.Release.Number returns the version number… (begins to enumerate a set) + +> Variables let you adjust a deployment's behavior based on its context, so you can avoid hardcoding values that change between environments… (teaches the model and the "why" which belong in concept pages or topics) + +## Reference topics + +**Required — one or more** + +The body of a reference page is built from reference topics, each authored to the reference topic standard. Every topic's title renders as an H2. + +Reference topics MUST: + +- Each conform to the reference topic standard +- Enumerate sets that belong to the same subject — the subject named by the page title + +Reference topics MUST NOT appear if they enumerate a set unrelated to the page's subject. + +Reference topics SHOULD be split by the natural boundaries of the sets, not collapsed into one oversized table. When a page covers several distinguishable sets, each set earns its own reference topic. + +### Reference topic examples + +A well-formed set of reference topics for the page "System variables": + +- Release variables +- Deployment variables +- Action variables +- Step variables +- User-modifiable settings + +Each enumerates a distinguishable set of variables. All belong to the page's subject enumerating the built-in variables Octopus provides. + +A poorly-formed set of reference topics for the same page: + +- Release variables +- Deployment variables +- Writing variable expressions + +"Writing variable expressions" discusses the Octostache model making it conceptual content. It belongs on a concept page. + +Another poorly-formed set of reference topics for "System variables": a single "Variables" topic containing every system variable across all distinguished sets in a single table. + +## Version notes + +**Optional** + +Where the page carries caveats tied to specific self-hosted Octopus versions, collect them in a Version notes block as the last element before Related links. See the version notes standard for what belongs here and how each entry is formed. This element does not appear on pages that have no version-specific caveats. + +## Related links + +**Optional** + +Related links point the reader to where to go after the lookup: the concept page that explains the model behind these sets, guides that put the values to use, or adjacent reference pages. + +Related links SHOULD: + +- Appear on most reference pages, as a reader who's looked something up usually has a next destination +- Include the concept page that explains the model behind the enumerated sets, where one exists + +Related links MUST NOT: + +- Include links that don't resolve +- Exceed five links + +### Related link examples + +A well-formed set of related links for the page "System variables": + +- Variable substitutions +- Runbook variables +- Output variables + +A poorly-formed set of related links for the same page: + +- Coming soon: system variable changelog (placeholder that doesn't resolve) +- Links to all fourteen pages that mention a variable (associative, not navigational; exceeds five) + +## Composition rules + +These rules govern how the topics above are assembled into a page. + +### Scope + +A reference page covers a single coherent subject: one set, or several related sets a reader looks up together. Every reference topic on the page MUST enumerate a set that belongs to that subject. A reader who lands to look up one value should find the related sets alongside it, and not sets that belong to a different subject. + +- Do this: A "System variables" page enumerating release, deployment, action, and output variables. Different scopes, one subject: the built-in variables Octopus provides. +- Not this: A "System variables" page that also enumerates the built-in user roles. User roles are a different subject with their own reference page. + +### Topic order + +Reference topics have no inherent order. Unlike concept and guide pages, no topic depends on another and no topic must be read before another. A reader may consult "Action variables" without needing to read "Release variables." Order therefore serves lookup speed, not comprehension. + +Reference topics MUST NOT be ordered by dependency or narrative. There's no "read this first." + +Reference topics SHOULD be ordered for lookup, by whichever of these fits the set: + +- The product's own order, when the sets mirror something with an established order in the UI or artifact, for example the order that settings are listed in the UI. A reader who knows the product predicts where to look. +- Alphabetical, when there's no meaningful product order. + +- Do this: On "System variables," order the topics by variable scope as they occur in a deployment's lifecycle (release → deployment → action → output), matching how the product surfaces them. +- Not this: Order the topics by how commonly the Octopus development team thinks each is used. "Commonly used" is a judgment call a reader can't predict, so it defeats lookup. + +### Heading structure + +The heading structure is important for reader scannability and for LLM retrieval. Follow these constraints: + +- The page MUST have exactly one H1: the title, from frontmatter. +- Each reference topic's title renders as an H2. +- A topic MAY use an H3 for an internal subsection where one is genuinely needed. Use sparingly. +- H4 and deeper MUST NOT be used. + +A reference page with exactly one reference topic MUST collapse the topic's title into the page H1. The page carries no H2 for its sole topic. The topic's short description follows the introduction directly. Because reference page and reference topic titles share the same convention (a noun phrase naming the set), the H1 satisfies both. + +On a single-topic page, the introduction and the topic's short description sit adjacent with no heading between them. Fold the topic's scope statement into the introduction rather than repeating it. + +### Permitted and forbidden topic types + +A reference page MUST contain only reference topics. + +A reference page MUST NOT contain concept topics. This is the most important boundary on the page. A page that needs to teach a model — how the sets relate, why they exist, when to reach for one — is a concept page that may carry reference topics, not a reference page that carries a concept topic. When a reference page seems to want conceptual framing, that framing belongs on a concept page, linked from related links. + +A reference page MUST NOT contain task topics. A page whose reader's job is to complete a procedure is a guide page. Link to the guide from related links. + +Troubleshooting, glossary, and release-note topics each have their own deliverables and MUST NOT appear. + +## Template + +For reference pages that collect multiple reference topics: + +``` +--- +# Frontmatter — see the frontmatter standard. +# type MUST be: reference +--- +[Introduction. One or two sentences naming what the page enumerates and +orienting the reader to the sets ahead, plus any caveat that applies across +all topics. No heading.] +## [Reference topic 1 title] <!-- noun phrase naming the set --> +[Short description, then the reference table.] +## [Reference topic 2 title] +[Short description, then the reference table.] +## [Reference topic 3 title] +[Short description, then the reference table.] +## Version notes <!-- optional; self-hosted versions only; before Related links --> +## Related links <!-- optional; up to five, no placeholders --> +- [The concept page that explains the model behind these sets] +- [An adjacent reference page] +``` + +For reference pages that render a single reference topic: + +``` +--- +# Frontmatter — see the frontmatter standard. +# type MUST be: reference +# title names the set (serves as both page and topic title) +--- +[Introduction, with the sole topic's scope statement folded in. No heading.] +[Short description, then the reference table — no H2, directly after the intro.] +## Related links +- [The concept page that explains the model behind this set] +``` + +## Examples + +Here's a short, complete reference page. It enumerates three variable scopes as separate reference topics, framed by an introduction carrying the page-wide "all strings" caveat, with related links pointing to the concept page that explains how the values are used. Tables are abbreviated for length; a real page enumerates each set completely. + +``` +--- +title: System variables +sidebarLabel: System variables +navOrder: 2 +description: The built-in variables Octopus provides for use in deployment processes, runbooks, and scripts. +subject: system variables, deployment variables, output variables, Octostache +type: reference +audience: [devops-eng, power-user] +image: +imageAlt: +--- +This page lists the built-in variables Octopus provides for use in deployment +processes, runbooks, and custom scripts. Variables are grouped by the scope +they're drawn from. All Octopus variables are strings, even when the value +looks like a number or boolean. +## Release variables +Release-level variables are drawn from the project and release being created. +| Variable | Description | Example | +|-------------------------|----------------------------------------------------|---------------| +| Octopus.Release.Id | The ID of the release. | releases-123 | +| Octopus.Release.Number | The version number of the release. | 1.2.3 | +| Octopus.Release.Notes | Release notes associated with the release (Markdown).| Fixes bug 1 | +## Deployment variables +Deployment-level variables are drawn from the project and release being deployed. +| Variable | Description | Example | +|-------------------------|----------------------------------------------------|--------------------| +| Octopus.Deployment.Id | The ID of the deployment. | deployments-123 | +| Octopus.Deployment.Name | The name of the deployment. | Deploy to Production| +| Octopus.Deployment.Error| The error/exit code for a failed deployment. | Script returned exit code 123 | +## Action variables +Action-level variables are available during execution of an action. +| Variable | Description | Example | +|----------------------|-----------------------------------------------------|----------| +| Octopus.Action.Id | The ID of the action. | 85287bef | +| Octopus.Action.Name | The name of the action. | Website | +| Octopus.Action.Number| The sequence number of the action in the process. | 5 | +## Related links +- [Variable substitutions](http://path/to/doc) +- [Output variables](http://path/to/doc) +- [Runbook variables](http://path/to/doc) +``` + +Why this is well-formed: the introduction orients the reader to the sets ahead and carries the one caveat true across every topic ("all strings"), without teaching a model or enumerating entries. Each topic is a genuine set with a short description stating what that scope draws from. The topics are ordered by lifecycle scope (release → deployment → action), matching how the product surfaces them. Related links leads with the concept page that explains how the values are used — the "why" the reference page deliberately omits. + +Here's a reference page with a single reference topic. The set is small and complete, so it needs only one topic — which means the topic title collapses into the page H1, the introduction absorbs the topic's scope statement, and the table follows the introduction directly with no H2. + +``` +--- +title: Loop iteration variables +sidebarLabel: Loop iteration variables +navOrder: +description: The special variables available inside an each loop in a variable template. +subject: iteration variables, each loop, Octostache, templates +type: reference +audience: [devops-eng, power-user] +image: +imageAlt: +--- +This page lists the special variables Octopus makes available inside an `each` +loop when evaluating a variable template. Each variable reports the position of +the current element in the collection being iterated. All values are strings. +| Variable | Description | +|------------------------------|-------------------------------------------------------------------| +| Octopus.Template.Each.Index | Zero-based index of the current element in the iteration. | +| Octopus.Template.Each.First | "True" if the element is the first in the collection, otherwise "False".| +| Octopus.Template.Each.Last | "True" if the element is the last in the collection, otherwise "False". | +## Related links +- [Variable substitutions](http://path/to/doc) +``` + +Why this is well-formed: with one set, there's one topic, so its title becomes the H1 — legal because reference page and reference topic titles share the same convention. There's no H2 for the sole topic. The introduction carries what would otherwise be the topic's short description (what the set enumerates, its scope — inside an each loop, and the "strings" caveat), so orientation appears once, not twice. The table follows the introduction directly. Related links points to the concept page that explains iteration, where this set is put to use. diff --git a/contributing/standards/reference-topic.md b/contributing/standards/reference-topic.md new file mode 100644 index 0000000000..7909ec95a3 --- /dev/null +++ b/contributing/standards/reference-topic.md @@ -0,0 +1,235 @@ +# Reference topic + +A reference topic enumerates a complete set of options, values, commands, or requirements in a structured, scannable, table format. It does not explain or instruct. It describes what exists and what it does. Reference topics are used in hand-authored documentation (as opposed to auto-generated API or CLI references) delivered as optional supporting topics within articles. + +## Reference topic elements + +Reference topics contain the following elements in order: + +- Title* +- Short description* +- Reference table* +- Examples + +(* = required) + +## Title + +**Required** + +Write reference topic titles as noun phrases that name the enumerated set or the artifact being documented, using the terms that appear in the product. Where a concept title names an idea, a reference title names the concrete thing a reader looks up, like a file, a list of configuration settings, or a list of requirements. + +Reference topic titles MUST: + +- Be a noun phrase +- Name the set, artifact, or collection being enumerated +- Use the canonical product term as it appears in the UI or the artifact +- Be unique from other topic titles + +Reference topic titles MUST NOT: + +- Use verbs, gerunds, or question framing +- Exceed 60 characters + +### Title examples + +Well-formed titles for reference topics: + +- Built-in user roles +- System requirements +- Deployment target settings + +Poorly-formed titles for reference topics: + +- Configuring deployment targets (gerund; names an action, not a set) +- Deployment targets (names the idea, not the enumerated set) +- What are the system requirements? (question framing) + +## Short description + +**Required** + +The short description is the opening paragraph of the topic. It states what the table enumerates and where the reference applies, for example the version or product context the values are valid for. It does not define concepts or provide steps for completing tasks. + +Reference topic short descriptions MUST: + +- State what the table enumerates +- State where the reference applies (version, subscription, or product scope) wherever that affects the values +- Note explicitly when the enumerated set is partial rather than complete + +Reference topic short descriptions MUST NOT: + +- Restate the title +- Explain why the reader would care, or when to use the thing +- Begin describing individual entries (these belong in the reference table) + +### Short description examples + +A well-formed short description for "Built-in user roles": + +> Octopus ships with a set of built-in user roles. This topic lists each built-in role and the permissions it grants. Roles introduced in later versions of Octopus are not added to existing built-in roles automatically. + +Poorly-formed short descriptions for the same reference: + +> Built-in user roles are the user roles that are built into Octopus. (restates the title; states no scope) + +> User roles play a major part in the Octopus security model. They're assigned to teams and dictate what members can do, so getting them right matters for keeping your instance secure. (security-model framing and rationale belong in a concept topic) + +> The first role, Build Server, lets build servers publish packages and create releases and deployments… (begins describing individual entries) + +## Reference table + +**Required** + +The reference table is the main body and majority of the topic. It displays every member of the enumerated set in a structured, scannable form so a reader can locate one entry without reading the others. The table doesn't explain why the set matters or how to use it (these are handled through related links). It states what each item is and what it does. + +Reference tables MUST: + +- Display the enumerated set as a table +- Be complete and enumerate every item of the set +- Use consistent phrasing, structure, and level of detail across the rows (parallel structure) +- Follow logical and predictable ordering, either alphabetical or the order the items appear in the UI +- Keep every cell factual and descriptive + +Reference tables MUST NOT: + +- Contain procedural content +- Contain conceptual framing +- Interleave other topic types into the table flow + +The table's columns follow the natural structure of the set. Common formats include: + +- A properties table (name, type, default, description) for settings, schema, and variables +- A comparison matrix (items down one axis, capabilities or editions across the other) for permissions and feature support +- A requirements list (component to requirement) for system requirements and compatibility. Choose the columns the set demands + +### Reference table examples + +A well-formed reference table for the reference topic "Built-in user roles": + +| User role | Description | +|---|---| +| Build Server | Can publish packages and create releases, deployments, runbook snapshots, and runbook runs. | +| Certificate Manager | Can edit certificates and export private keys. | +| Deployment Creator | Can create deployments and runbook runs. | +| Project Viewer | Can view a project, its releases, and its deployments, but cannot edit them. | +| Project Contributor | Can do everything a Project Viewer can, plus edit variables and deployment steps. Cannot create or deploy releases. | +| Project Deployer | Can do everything a Project Contributor can, plus deploy releases. Cannot create them. | +| System Administrator | Can perform every action at the system level. | + +A poorly-formed reference table for the same topic: + +| User role | Description | +|---|---| +| Build Server | Build servers can publish packages and create releases. | +| Package Publisher | Permits packages to be pushed to the built-in feed. | + +> Rather than modifying the built-in roles, we recommend leaving them as examples and creating your own. +> +> To create a custom user role, go to Configuration and select Roles, then select Add custom role… +> +> If a user has more or fewer permissions than expected, use the Test Permissions feature to see every permission a user holds. + +This fails on several counts. Row phrasing isn't parallel. Three other topic types have been folded into running text: a recommendation, a procedure, and a troubleshooting line. + +## Examples + +**Optional, highly recommended** + +Examples show the enumerated set applied in a real, concrete context to help readers understand what settings, permissions, requirements, etc., enable in their real-world use cases. Where the table tells the reader what each item is, examples show how items are applied or work with other concepts. + +Examples MUST: + +- Show an item from the table applied in a realistic, representative case +- Stay consistent with the table +- Be illustrative, not exhaustive (show one representative case) + +Examples MUST NOT: + +- Become a procedure +- Introduce conceptual framing or recommendations +- Introduce items not present in the table + +### Examples of the example element + +A well-formed example for the reference topic "Built-in user roles": + +> A release manager who approves production deployments but doesn't author them might be assigned Project Lead (to create releases) scoped to all projects, plus Project Deployer scoped only to the Production environment. + +A poorly-formed example for the same topic: + +> To set up a release manager, go to Configuration > Teams, select Add Team, add the user, then assign Project Lead and Project Deployer and set the environment scope to Production. (this is a procedure, it doesn't explain how the settings are applied in a realistic use case) + +## Full examples + +Here's an example of a well-formed reference topic: + +--- + +**Built-in user roles** + +Octopus ships with a set of built-in user roles. This topic lists each built-in role and the permissions it grants. Roles introduced in later versions of Octopus are not added to existing built-in roles automatically. + +Octopus includes the following built-in user roles, listed alphabetically: + +| User role | Description | +|---|---| +| Build Server | Can publish packages and create releases, deployments, runbook snapshots, and runbook runs. | +| Certificate Manager | Can edit certificates and export private keys. | +| Deployment Creator | Can create deployments and runbook runs. | +| Environment Manager | Can view and edit environments and their machines. | +| Environment Viewer | Can view environments and their machines, but cannot edit them. | +| Package Publisher | Can push packages to the Octopus Server built-in feed. | +| Project Contributor | Can do everything a Project Viewer can, plus edit variables and deployment steps. Cannot create or deploy releases. | +| Project Deployer | Can do everything a Project Contributor can, plus deploy releases. Cannot create them. | +| Project Lead | Can do everything a Project Contributor can, plus create releases. Cannot deploy them. | +| Project Viewer | Can view a project, its releases, and its deployments, but cannot edit them. | +| Release Creator | Can create releases and runbook snapshots. | +| Runbook Consumer | Can view and run runbooks. | +| Runbook Producer | Can edit and run runbooks. | +| System Administrator | Can perform every action at the system level. | +| System Manager | Can perform every system-level action except those reserved for System Administrators. | +| Tenant Manager | Can edit tenants and their tags. | + +A release manager who approves production deployments but doesn't author them might be assigned Project Lead (to create releases) scoped to all projects, plus Project Deployer scoped only to the Production environment. + +--- + +Here's an example of a poorly-formed reference topic: + +--- + +**User roles** + +User roles and group permissions play a major part in the Octopus security model. These roles are assigned to teams, and they dictate what the members of those teams can do in Octopus. Octopus comes with a set of built-in user roles designed to work for most common scenarios. + +| User role | Description | +|---|---| +| Build Server | Build servers can publish packages, and create releases, deployments, runbook snapshots and runbook runs. | +| Certificate Manager | Certificate managers can edit certificates and export private-keys | +| Project Viewer | Project viewers have read-only access to a project. They can see a project in their dashboard, view releases and deployments. Restrict this role by project to limit it to a subset of projects, and restrict it by environment to limit which environments they can view deployments to. | +| System Administrator | System administrators can do everything at the system level. | + +The built-in user roles can be modified, but instead of modifying them, we recommend that you leave them as an example and create your own user roles. + +**Creating user roles** + +A custom user role can be created with any combination of permissions. To create a custom user role: + +1. Under the Configuration page, click Roles. +2. Click Add custom role. +3. Select the permissions you'd like this role to contain, and give the role a name and description. + +**Troubleshooting permissions** + +If a user has more or fewer permissions than they should, use the Test Permissions feature to get a readable list of all permissions a specific user has. Go to Configuration ➜ Test Permissions and select a user from the drop-down. + +--- + +Why is this poorly-formed? + +- The short description is concept content. It explains the security model and why roles matter — the "why" that a reference deliberately omits and links out to instead. It also fails to state where the reference applies or its scope. +- The set is incomplete with no statement that it's partial. The legacy product lists seventeen built-in roles plus the space-level Space Manager; showing four without flagging the omission breaks the completeness rule. +- The "Creating user roles" section is a task. Procedural steps and UI navigation belong in a task topic, linked from related links, not folded into the reference body. +- The "Troubleshooting permissions" section is troubleshooting content. Like the procedure, it's a separate topic type that's been absorbed into what should be a single lookup. +- The result is one topic trying to do four jobs (concept, reference, task, and troubleshooting) so none is scannable or retrievable on its own. diff --git a/contributing/standards/task-topic.md b/contributing/standards/task-topic.md new file mode 100644 index 0000000000..1f09e91a37 --- /dev/null +++ b/contributing/standards/task-topic.md @@ -0,0 +1,327 @@ +# Task topic + +A task topic provides step-by-step instructions for completing a single, discrete action. Each step contains one action. The topic includes explicit prerequisites, a stated result, and optional next steps. Task topics are the primary building block of how-to pages and the procedural backbone of guide pages. + +## Task topic elements + +Task topics contain the following elements in order: + +- Title* +- Short description* +- Prerequisites +- Steps* +- Result +- Troubleshooting +- Next steps + +(* = required) + +## Title + +**Required** + +Write task topic titles as commands (imperative verb phrases) that name a single action, using the terms that appear in the product. The title states what the reader will accomplish, beginning with the verb. Where a procedure differs by platform, stack, or vendor, write a separate task with its own title rather than one title covering multiple procedures. + +Task topic titles MUST: + +- Begin with a command (commonly create, add, view, edit, delete) +- Name exactly one action +- Use the canonical product term for the object of the action as it appears in the UI +- Be unique from other topic titles + +Task topic titles MUST NOT: + +- Use gerunds, noun-phrase-only forms, or question framing +- Bundle multiple procedures into one title +- Exceed 60 characters + +### Title examples + +Well-formed titles for task topics: + +- Add a deployment target +- Install Octopus Server on a Windows VM +- Install Octopus Server on a Linux host with Docker +- Create a deployment process + +Poorly-formed titles for task topics: + +- Adding a deployment target (uses a gerund) +- Deployment target confirmation (noun phrase, no action) +- How do I install Octopus Server? (uses question framing) +- Create and configure a runbook (bundles two procedures and should be split) + +## Short description + +**Required** + +The short description is the opening paragraph of the topic. It states what completing the task accomplishes and why the reader would do it. It orients a reader who arrived looking for steps. It does not teach the concept or begin the procedure. + +Short descriptions MUST: + +- State what completing the task accomplishes +- Identify when to perform the task, where that isn't self-evident from the title + +Short descriptions MUST NOT: + +- Restate the title +- Contain or pre-empt the steps +- Carry extended conceptual explanation — push that to the optional concept intro at the page level + +### Short description examples + +A well-formed short description for the task "Add a deployment target": + +> A deployment target must be set up in Octopus before any deployment process can run against it. Follow these steps to register a single target and assign it to an environment. This makes the deployment target available to the steps that deploy there. + +Poorly-formed short descriptions for the same task: + +> This task explains how to add a deployment target. (restates the title) + +> First, go to Infrastructure > Deployment Targets and select Add Deployment Target… (pre-empts the steps; the procedure belongs in the steps element) + +> A deployment target represents a unit of infrastructure, such as a Windows server running a Tentacle, a Linux machine reached over SSH, or a Kubernetes cluster. Each target belongs to one or more environments… (this belongs in a concept topic at the top of a page, not in a task topic) + +## Prerequisites + +**Required when they exist** + +Prerequisites list what must already be true before the reader starts. Each item is a single, verifiable condition. Omit the block entirely when the task has no prerequisites. + +Prerequisites MUST: + +- State each condition as a single checkable item, in an unordered list +- Link to the task that satisfies the condition, where one exists +- Be limited to genuine blockers — things that will cause the procedure to fail if missing + +Prerequisites MUST NOT: + +- Contain steps or instructions. A prerequisite names a required state. It doesn't tell the reader how to reach it. +- List general background knowledge that isn't a checkable condition. For example, "familiarity with deployments." + +### Prerequisites examples + +Well-formed prerequisites for the task "Add a deployment target": + +> **Before you begin** +> +> You'll need: +> +> - An environment to assign the target to. Learn more about environments. +> - A Tentacle agent installed on the target machine, or SSH access to it. Learn more about Tentacles. +> - The Infrastructure permission in the space. Learn more about permissions. + +Poorly-formed prerequisites for the same task: + +> Before you start, install the Tentacle agent by downloading it from the downloads page, running the installer, and selecting the listening or polling mode that matches your network. (this is a procedure; link to the install task instead of rewriting it) + +## Steps + +**Required** + +Steps are the procedure. Each step is one action, written as an imperative instruction beginning with the verb. Steps are ordered, sequential, and assume the reader performs them in order. The procedure covers the single, happy, recommended path for completing the task (even if there are multiple ways to achieve the desired result). + +Steps MUST: + +- Be presented as an ordered (numbered) list, never a bulleted list. +- Be introduced by a lead-in line that names the procedure; the list never floats on its own +- Contain exactly one action per step +- Begin with an imperative verb and state the location before the action (where to be, then what to do) +- Use bold treatment for UI labels and mirror the casing shown in the UI +- Use `>` for navigation paths +- Use backticks for parameters, file paths, and commands +- Be free of conditional branching. If the procedure forks by platform, stack, or vendor, split it into separate task topics. + +Steps MUST NOT: + +- Combine multiple actions in one step +- Carry conceptual explanation — if a step needs a caveat or rationale, use a note admonition, not body prose inside the step +- Nest beyond one level of substeps + +Steps MAY: + +- Include inline screenshots, sparingly (see Inline screenshots in steps below) + +### Steps examples + +Well-formed steps for the task "Add a deployment target": + +> To add a deployment target: +> +> 1. From the project dashboard, select **Infrastructure > Deployment Targets**. +> 2. Select **Add Deployment Target**. +> 3. Select the target type that matches your infrastructure. +> 4. Enter the requested configuration details, including at least one **Environment** and **Target** tag. See related links for specific guidance per type of deployment target. + +Poorly-formed steps for the task "Add a deployment target": + +> Navigate to the Infrastructure section of the nav, click Deployment Targets, then click Add Deployment Target and select the type of target you want. Tentacle targets communicate over a secure channel. You can either listen or poll using tentacles… (does not use a numbered list, has no lead-in, combines three actions, and embeds conceptual content) + +### Inline screenshots in steps + +Screenshots in a task are verification aids attached to a specific step. They are not high-level diagrams. Add one only when it earns its place. + +Include a screenshot when: + +- The reader might struggle to locate an item in the UI +- The procedure moves from one area of the UI to another +- It confirms the reader has reached the expected state before continuing + +Screenshots MUST: + +- Sit directly beneath the step they support, as continuation content of that step. They must not appear as their own numbered or bulleted list item. +- Include alt text describing what the image shows. +- Supplement the step, never replace it. The written instruction must stand alone for readers who can't see the image. + +Screenshots MUST NOT: + +- Appear for steps that are unambiguous from the text alone + +A screenshot that's proposed but not yet created uses the SUGGESTED VISUAL marker defined in content-conventions.md, never visible body copy. Once the screenshot exists, embed it with standard Markdown image syntax and alt text per the rules above — that's what the `[Screenshot: …]` notation in this standard's worked example below represents: an embedded image's placement and alt text, not an unresolved suggestion. + +## Result + +**Optional, highly recommended** + +The result states the observable outcome of completing the steps, so the reader can confirm they succeeded. Include it whenever the outcome can be stated accurately. Where there's no visible confirmation in the UI, the result can include a verification instruction the reader can run. + +Prefer omission over fabrication. If you cannot state the outcome accurately, drop the element rather than invent one. + +Results MUST: + +- Describe an outcome the reader can actually observe, or give a verification step they can run +- Be a single statement of the state achieved by successfully completing the associated steps + +Results MUST NOT: + +- Restate the final step verbatim +- Introduce steps the procedure left out +- Assert an outcome the author can't verify + +### Result examples + +A well-formed result for the task "Add a deployment target" for targets with a visible outcome in the UI: + +> The target appears in the Deployment targets list with a green Healthy status once Octopus completes its first health check. + +A well-formed result for the task "Add a deployment target" for targets with no visible outcome in the UI: + +> You can confirm that the target is reachable by running a health check from the target's overview page. + +A poorly-formed result for the same task: + +> The deployment target has been added successfully. (restates the final step and gives the reader nothing observable to check against) + +## Troubleshooting + +**Optional** + +A single link to the troubleshooting topic that covers failures of this task, for a reader whose result didn't match. Troubleshooting content lives in its own standalone topic. A task topic links to it rather than embedding recovery steps. Place this element immediately after the result, so a reader who didn't reach the expected outcome finds the recovery path at the point of friction. + +Troubleshooting MUST: + +- Be a single link to a troubleshooting topic that covers failures of this task +- Be framed as recovery (the condition, then where to go) +- Be omitted entirely when no troubleshooting topic exists for the task + +Troubleshooting MUST NOT: + +- Invent or link to a troubleshooting topic that doesn't exist, to fill the element. Prefer omission over fabrication. +- Contain troubleshooting steps inline. Recovery content belongs in the troubleshooting topic, not the task. +- List more than one troubleshooting link. Many failure modes are one troubleshooting topic covering them, not many links. + +### Troubleshooting examples + +A well-formed troubleshooting link for the task "Add a deployment target": + +> If the target doesn't reach a healthy status, see Troubleshoot deployment targets. + +A poorly-formed troubleshooting link for the same task: + +> For more help, see the troubleshooting page, the Tentacle docs, the SSH guide, and the community forum. (multiple links; not specific to this task's failure; mixes recovery with general discovery) + +## Next steps + +**Optional** + +Next steps point the reader to the single most likely forward action in their workflow. They briefly describe what to do next to keep making progress after this task. They are not a list of everything that may be related to the task. + +Next steps MUST: + +- Point to a logical follow-on task in the same workflow +- Be framed as forward motion, with the action stated + +Next steps MUST NOT: + +- List more than two or three onward paths + +### Next steps example + +Well-formed next steps for the task "Add a deployment target": + +> After adding deployment targets, you can now add a deployment step that deploys to the target. + +## Examples + +Here's an example of a well-formed task topic: + +--- + +**Add a deployment target** + +A deployment target must be set up in Octopus before any deployment process can run against it. Follow these steps to register a single target and assign it to an environment. This makes the deployment target available to the steps that deploy there. + +**Before you begin** + +You'll need: + +- An environment to assign the target to. Learn more about environments. +- A Tentacle agent installed on the target machine, or SSH access to it. Learn more about Tentacles. +- The Infrastructure permission in the space. Learn more about permissions. + +To add a deployment target: + +1. From the project dashboard, select **Infrastructure > Deployment Targets**. +2. Select **Add Deployment Target**. +3. Select the target type that matches your infrastructure. + <!--[Screenshot: the Add Deployment Target screen showing the available target types. Alt text: "The Add Deployment Target screen with target type options."]--> +4. Enter the requested configuration details, including at least one **Environment** and **Target** tag. See related links for specific guidance per type of deployment target. + +The target appears in the Deployment targets list with a green Healthy status once Octopus completes its first health check. + +If the target doesn't reach a healthy status, see Troubleshoot deployment targets. + +After adding a deployment target, you can add a deployment step that deploys to the target. + +--- + +Here's an example of a poorly-formed task topic: + +--- + +**How do I add and configure a deployment target?** + +This topic explains how to add and configure a deployment target. A deployment target represents a unit of infrastructure, such as a Windows server running a Tentacle, a Linux machine reached over SSH, or a Kubernetes cluster. Each target belongs to one or more environments and carries tags that connect it to the steps in a deployment process. + +You should be familiar with deployments and how Octopus works. First, install the Tentacle agent by downloading it from the downloads page, running the installer, and selecting the listening or polling mode that matches your network. + +Navigate to the Infrastructure section of the nav, click Deployment Targets, then click Add Deployment Target and select the type of target you want. Tentacle targets communicate over a secure channel and can either listen or poll. + +If you're on Windows, install a Tentacle and choose a communication mode. If you're on Linux, set up SSH access instead and skip the Tentacle steps. + +Fill in the fields and save. + +The deployment target has been added successfully. + +Add a deployment step. See also Deployment targets, Environments, Deployment target tags, Workers, Variables, Channels, Lifecycles, and Projects. + +--- + +Why is this poorly-formed? + +- The title uses question framing and bundles two procedures (add and configure). It should be a single command naming one action, and the two procedures should be split into separate task topics. +- The short description restates the title and then dumps conceptual content — what a deployment target is and how it relates to environments and tags. That explanation belongs in a concept topic at the top of the page, not in the task. +- The prerequisites list general background knowledge ("familiar with deployments"), which isn't a checkable condition, and then inlines the Tentacle install as a procedure. A prerequisite names a required state and links to the task that satisfies it. It doesn't rewrite that task. +- The steps are a bulleted list with no lead-in. The first step combines three actions and embeds conceptual explanation about Tentacle communication. The second step branches by platform. This signals two task topics. The third step ("Fill in the fields and save") is too vague to follow. +- The result restates the final step and gives the reader nothing observable to verify against. +- Next steps lists far more than two or three onward paths. diff --git a/contributing/standards/tutorial-page.md b/contributing/standards/tutorial-page.md new file mode 100644 index 0000000000..f8b8690cbc --- /dev/null +++ b/contributing/standards/tutorial-page.md @@ -0,0 +1,310 @@ +# Tutorial page + +A tutorial page is a content deliverable that teaches a new user how Octopus works by having them build something tangible. It threads concepts and procedures together so the reader learns by doing: each step advances a single worked example, and each concept is introduced at the moment the step needs it. + +A tutorial page is for learning, not for reference and not for real work. It answers "I'm new — show me how this fits together by walking me through it once." Unlike a guide page, the reader does not arrive with their own goal or their own values to plug in — the tutorial states the goal, provides an example, and ensures one successful path from start to finish. + +This is the boundary that separates a tutorial from a guide: + +- A guide page serves a reader who has their own job and their own inputs. It is a recipe they apply to their situation. It may branch ("if you're on Windows…"). +- A tutorial page manufactures the job and provides the inputs. It is a single guaranteed path with no branching. Success is the reader finishing, not the reader solving a problem they brought with them. + +The mechanical test is **whose goal, and whose example?** If both belong to the reader, it's a guide. If both are supplied by the page, it's a tutorial. + +Because a tutorial's value comes from one continuous worked example, its topics are authored for this page only. A tutorial's "Create a project" topic is written around the tutorial's running example and is not the canonical, reusable task topic for creating a project. Tutorial topics are exempt from reuse. This is the one place topic authorship bends, and it bends by design. + +## Tutorial page elements + +A tutorial page contains the following elements in order: + +- Frontmatter*, including a title +- Introduction* +- Concept and task topics*, interleaved +- Wrapping up + +(* = required) + +A tutorial page is assembled from the same concept topics and task topics as the other deliverables, authored to their existing standards. What differs is how they are arranged and what they may do, governed by the tutorial composition rules below. Each topic renders as an H2. + +Concept material is interleaved just in time: a short concept topic placed immediately before the task that needs the model it establishes. A tutorial page differs from a guide page in one structural way that the composition rules make explicit: on a tutorial, concept topics MAY be the page's primary content, because teaching is the page's job. On a guide, they must not. + +The running example, the transitions between topics, and the closing reflection are what make the sequence read as one continuous walkthrough rather than a list of procedures. They SHOULD appear but are not required. + +## Title conventions + +The frontmatter standard governs the title field for any document in the repository. Titles appear as the H1 and the page's `<title>` metadata element, used for SEO and LLM retrieval. + +A tutorial title names what the reader will build by the end, framed as a guided first run. + +Tutorial page titles MUST: + +- Signal a guided first-run, by opening with either "Your first…" or "Get started with…" +- Name the tangible thing that the reader builds or the outcome they reach, not the features they use to get there. +- Be 60 characters or fewer + +Tutorial page titles MUST NOT: + +- Be a gerund phrase ("Managing deployment targets") +- Be a bare feature noun ("Deployment targets") + +Well-formed tutorial page titles: + +- Your first deployment +- Get started with Octopus Deploy +- Your first runbook + +Poorly-formed tutorial page titles: + +- Deploying your first application (gerund) +- Deployments (bare feature noun) +- Tutorial (names the genre, not what the reader builds) +- Deploy your first application (bare imperative) + +## Introduction + +**Required** + +The introduction is the opening prose beneath the H1, before the first topic. In tutorials, the introduction sets up the worked example the whole page runs on, and it tells the reader what they'll have built by the end. It has no heading of its own. + +The introduction MUST: + +- State what the reader will build and see working by the end of the page +- Orient the reader to the walkthrough ahead + +The introduction SHOULD: + +- Introduce the running example the tutorial uses, where the tutorial has one +- State what the reader needs before starting, where anything is assumed — an account, an install — kept to one line + +The introduction MUST NOT: + +- Contain procedural steps +- Teach the concepts in depth +- Contain a heading + +### Introduction examples + +A well-formed introduction for the tutorial "Your first deployment": + +> In this tutorial you'll deploy a small sample web app to a test environment and watch it go live. You'll create a project, define a single deployment step, and push a release through it. You'll learn the same shape every real Octopus deployment takes, at the smallest scale that still works end to end. You'll need an Octopus Cloud account to follow along. + +Poorly-formed introductions for the same page: + +> A project is the container for everything Octopus needs to deploy your application: its deployment process, its variables, and its releases. A release is a versioned snapshot of that process. (teaches the concepts in depth) + +> Go to Projects, select Add Project, name it, and click Save to begin. (contains procedure steps that belong in a task topic) + +> Welcome! Deployments in Octopus are powerful, flexible, and easier than ever. (adds no orientation, states no outcome, and reads as promotional filler) + +## Concept and task topics + +**Required — one or more, interleaved** + +The body of a tutorial is a sequence of concept topics and task topics, each authored to its existing standard. Each topic renders as an H2. + +Nothing about how a concept topic or a task topic is written changes on a tutorial page. What changes is how they are arranged, and two permissions the tutorial page grants that no other deliverable does. + +### Concept topics + +A tutorial MAY use concept topics to establish the model a following task needs. Each is authored to the concept topic standard and placed immediately before the task that relies on it, never front-loaded ahead of all the work. + +Concept topics in a tutorial MUST: + +- Each conform to the concept topic standard +- Establish only the conceptual model the next task needs + +Concept topics in a tutorial MUST NOT front-load models the reader won't use until later in the tutorial. + +Unlike a guide page, concept topics on a tutorial MAY be the page's primary content. Teaching is the tutorial's job, so the balance between concept and task material is not constrained. + +### Task topics + +A tutorial MAY use task topics to present procedures that advance the walkthrough, each authored to the task topic standard. + +Task topics on a tutorial MUST: + +- Each conform to the task topic standard +- Advance the single running example, using the tutorial's concrete values rather than placeholders + +Task topics on a tutorial MUST NOT: + +- Include a Troubleshooting element. A tutorial guarantees a single working path. A step that fails often enough to need recovery is a defect in the tutorial to be fixed, not annotated. Recovery links also send a first-run reader off-page mid-walkthrough, breaking the guaranteed path. +- Include a Next steps element. Forward motion between tasks is carried by the tutorial's transitions, not by per-topic next steps that would only point to the next H2 on the same page. + +Task topics on a tutorial are not canonical. A tutorial's "Create a project" is written around the running example and is not the reusable source for that operation. The same operation, authored for general use, belongs in its own guide page as the canonical, reusable task topic. + +## Wrapping up + +**Optional** + +Wrapping up is a short passage after the final task topic that closes the walkthrough: it marks what the reader accomplished and, where useful, points them where to go next now that they've done it once. It's the tutorial's send-off. The reader may have just spent a while learning, and this is where that effort pays off. It has no procedure and teaches no new concept. + +Unlike the introduction, which has no heading, this section falls at the end of the page after several topic H2s. It therefore takes its own H2, "Wrapping up", to separate it from the final task topic. + +Wrapping up SHOULD: + +- Acknowledge the accomplishment warmly. The reader built something real, and the send-off should feel like it. Let the delight come from naming the actual thing they achieved, not from exclamation. +- Restate the outcome the reader has achieved in a sentence. +- Connect the worked example back to the real work it stands in for, so the reader trusts they can now do this on their own. +- Point forward, where there's a sensible next destination. Link to the guide or concept page that takes this first run into real use, or the next tutorial in an onboarding sequence. Up to five links, none of them placeholders. + +Wrapping up MUST NOT: + +- Introduce a new concept or procedure +- Overclaim the reader's mastery ("you've deployed your first app," not "you're now an expert") +- Include links that don't resolve, or more than five + +### Wrapping up examples + +A well-formed wrapping up element for the tutorial "Your first deployment": + +> **Wrapping up** +> +> Nice work! You've run a real deployment using Octopus Deploy. You created a project, defined a deployment process, and pushed a release to a live environment, which is the same path every Octopus deployment follows, whatever you're shipping. You now have everything you need to set this up for your own application. +> +> Where to go next: +> +> - How the deployment process works +> - Managing deployment targets +> - Environments and lifecycles + +Poorly-formed wrapping up elements for the same page: + +> Congratulations! You're now an Octopus expert. 🎉 (overclaims mastery, orients the reader to nothing, and leans on exclamation instead of naming what was achieved) + +> To deploy to production, add a second environment and configure a lifecycle to promote releases between them. See also the twelve pages below that mention deployments. (introduces new procedure, then dumps an unfiltered associative link list) + +## Composition rules + +These rules govern how the topics above are assembled into a page. Where a rule matches the guide page or concept page standards it reads the same here on purpose. What's specific to a tutorial is the running example, the single path, and the just-in-time interleave. + +### Scope + +A tutorial page covers a single first-run journey: one worked example, carried from an empty starting state to one observable, working outcome. Every topic on the page MUST serve that journey. + +A tutorial's scope is set by the example, not by a feature. Like a journey guide, a tutorial may cross several features because the worked example needs them. What holds the page together is the single running example, not a feature boundary. + +### The running example + +A tutorial SHOULD run on one concrete worked example, introduced in the introduction and advanced by every task topic on the page. The example is what turns a sequence of procedures into a walkthrough. + +The running example SHOULD: + +- Be one example, carried from the first task to the last — one project, one app, one deployment, named once and reused +- Use concrete values, not placeholders — a reader following along types what they read +- Appear inside the task topics' steps, not only in the surrounding prose + +Once a tutorial has a running example, it MUST NOT change identity partway through. For example, a reader who created OctoFX in the first task must still be working on OctoFX in the last. + +### The single path + +A tutorial page MUST offer exactly one path from start to finish. No topic may fork the reader onto an alternative route. No "if you're on Windows, do this instead", no optional detours, no parallel platform tracks. + +Where a real feature genuinely forks, for example Cloud versus Self-hosted installation, the tutorial picks one path and commits to it. A tutorial that needs to teach two paths is two tutorials, or one tutorial and a guide page. + +### Topic order + +Topics on a tutorial follow the order the reader works in, with concept topics interleaved just in time. A reader must never reach a task that depends on a step they haven't done, or a task whose model the page hasn't yet given them. + +A concept topic MUST immediately precede the task whose model it establishes. Unlike a feature guide, a tutorial does not front-load a single concept topic ahead of all the tasks. Each concept lands at the point in the walkthrough where the reader is about to need it, and not before. + +- Do this: Projects (concept) → Create a project (task) → Deployments (concept) → Add a deployment step (task) → Releases (concept) → Create a release (task) → Deploy a release (task). The models that the user needs appear before the tasks that apply them; each task then advances the same example in the order the work happens. +- Not this: front-load Projects (concept), Deployments (concept), Releases (concept), then all four tasks. The reader has to hold multiple models in their head before doing anything. + +### Heading structure + +The heading structure is important for reader scannability and for LLM retrieval. Follow these constraints: + +- The page MUST have exactly one H1: the title, from frontmatter. +- Each concept and task topic's title renders as an H2. +- The "Wrapping up" send-off also takes an H2. It is the one H2 on a tutorial page that is not a composed topic. +- A topic MAY use an H3 for an internal subsection where one is genuinely needed. Use sparingly. +- H4 and deeper MUST NOT be used. Content that seems to need an H4 is a signal the topic is doing too much and should be split. + +### Permitted and forbidden topic types + +A tutorial page MUST contain only concept topics and task topics. + +A tutorial page MUST NOT contain reference, troubleshooting, glossary, or release-note topics: + +- Reference topics serve lookup, not first-run learning. A tutorial that stops to enumerate every option breaks the single path. Link to the reference from the "Wrapping up" element if the reader will want it later. +- Troubleshooting topics are never assembled into any page, and a tutorial guarantees a working path in any case. +- Glossary and release-note topics each have their own deliverables. + +## Template + +``` +--- +# Frontmatter — see the frontmatter standard. +# type MUST be: tutorial +--- +[Introduction. Two or three sentences: what the reader will build and see working by the end, the running example the page uses, and any one-line prerequisite. No heading.] +## [Concept topic 1 title] <!-- the model the first task needs, and no more --> +[Concept topic body, authored to the concept topic standard.] +## [Task topic 1 title] <!-- imperative: "Create a project" --> +[Task topic body, authored to the task topic standard, advancing the running example with concrete values. No Troubleshooting element, no Next steps element.] +## [Concept topic 2 title] <!-- lands just before the task that needs it --> +[Concept topic body.] +## [Task topic 2 title] +[Task topic body, advancing the same running example.] +## [Task topic 3 title] <!-- a task needs no preceding concept if its model is already established --> +[Task topic body.] +## Wrapping up +[Send-off: acknowledge what the reader built, restate the working outcome, connect it to their real work, and point forward. Up to five links, no placeholders.] +``` + +## Example + +Here's a short, representative tutorial page. It interleaves three concept topics with four task topics — each concept landing immediately before the task that needs it — threads one running example (OctoFX) from the first task to the last, and closes with a "Wrapping up" send-off. Task bodies are abbreviated to keep the example focused on tutorial structure; each is authored in full to the task topic standard. + +``` +--- +title: Your first deployment +sidebarLabel: Your first deployment +description: New to Octopus? Deploy a sample app end to end and learn how the core pieces fit together. +type: tutorial +audience: new-user +// Other frontmatter is discussed in the frontmatter standard +--- +In this tutorial you'll deploy a small sample web app, OctoFX, to a test +environment and watch it go live. You'll create a project, define a deployment +step, and push a release through it — the same path every Octopus deployment +follows, at the smallest scale that still works end to end. You'll need an +Octopus Cloud account to follow along. +## Projects +A project is where Octopus keeps everything it needs to deploy one application: +its deployment process, its variables, and its releases. Everything you do in +this tutorial lives inside a single project. +## Create a project +[Task topic body, authored to the task topic standard. Prerequisites, a lead-in, +and numbered steps that create a project named OctoFX. Result: the OctoFX project +appears on the Projects dashboard. No Troubleshooting element, no Next steps.] +## The deployment process +A deployment process is the ordered set of steps Octopus runs to deploy your +application. Each step does one part of the work — deploy a package, run a +script, update a service. Your OctoFX project needs one step to start. +## Add a deployment step +[Task topic body: adds a "Deploy a package" step to the OctoFX project's +deployment process, using the sample package. Result: the step appears in the +OctoFX process editor.] +## Releases +A release is a versioned snapshot of your deployment process and everything it +needs, frozen so you can deploy the same thing to each environment in turn. You +deploy a release, not the process directly. +## Create a release +[Task topic body: creates release 0.0.1 of the OctoFX project. Result: release +0.0.1 appears on the project's Releases page, ready to deploy.] +## Deploy a release +[Task topic body: deploys OctoFX release 0.0.1 to the Test environment. Result: +the deployment finishes with a green Success status, and OctoFX is live in Test.] +## Wrapping up +Nice work! You've run a real deployment using Octopus. You created the OctoFX +project, defined a deployment process, and pushed a release to a live +environment — the same path every Octopus deployment follows, whatever you're +shipping. You now have everything you need to set this up for your own +application. +Where to go next: +- [How the deployment process works](http://path/to/doc) +- [Managing deployment targets](http://path/to/doc) +- [Environments and lifecycles](http://path/to/doc) +``` diff --git a/contributing/standards/version-notes.md b/contributing/standards/version-notes.md new file mode 100644 index 0000000000..a0c4e3f626 --- /dev/null +++ b/contributing/standards/version-notes.md @@ -0,0 +1,123 @@ +# Version notes + +This standard governs the version notes element: an optional, page-level block that collects caveats tied to specific self-hosted Octopus versions. It is a cross-cutting standard. It applies to concept pages, guide pages, and reference pages. It sits alongside, not inside, the page and topic standards that govern body content. + +Version notes exist to keep version-specific detail out of the main body. A caveat that applies only to some self-hosted versions is noise for the reader on any other version, so it is lifted out of the prose where it would otherwise interrupt the majority case and collected in one block at the foot of the page. + +This element does NOT apply to tutorial pages. Tutorial pages MUST NOT carry version notes. + +The documentation set itself is not versioned. Version notes are how a single, unversioned page acknowledges that a detail differs across the self-hosted versions readers run. + +## What a version note is, and is not + +A version note records one of three things, each keyed to a self-hosted Octopus version: + +- Availability - a capability exists from a given version onward. +- Removal - a capability existed until a given version and no longer does. +- Behavior change - a capability worked one way before a given version and differently after. + +A version note is NOT: + +- A caveat true across every version the page addresses. That is ordinary body content and belongs in the prose or the introduction where it applies, not in this block. The test is whether a self-hosted version boundary changes the answer; if no boundary is involved, it is not a version note. +- A statement about Octopus Cloud. Cloud always runs the latest release and never carries a version caveat. Version notes reference self-hosted versions only, and MUST NOT be keyed to Cloud. +- An authoring marker. The `[VERIFY]` and `[PLACEHOLDER]` markers in `content-conventions.md` are pre-ship signals that never render to readers. A version note is finished, rendered content. The two MUST NOT be conflated. + +## Placement and heading + +The element MUST: + +- Use the exact H2 heading `Version notes`. +- Be the last body element on the page, immediately before Related links. + +The element renders only where needed. Unlike the frontmatter skeleton, it is not present-but-empty on pages that have no caveats. A page with nothing to note omits the heading and the block entirely. + +Placing version notes above Related links keeps Related links as the single terminal element across every page, and keeps the caveats inside the reading flow rather than stranded beneath the navigation the reader uses to leave. + +## What each entry contains + +Every entry MUST name three things: + +- The subject - the capability, setting, or behavior the caveat applies to. +- The version boundary - the self-hosted version or build the caveat is keyed to. +- What is true at that boundary - available from, removed in, or changed from/to. + +Naming the subject in every entry is what makes a collected, bottom-of-page block work. Lifted out of the prose, an entry that reads only "Available from 2024.2" is unreadable; the reader cannot tell what it refers to. The subject line is the cost of relocation, and it is mandatory. + +Each entry MUST: + +- Reference a self-hosted Octopus Server version or build, never Cloud. +- Record the version or build string exactly as the source states it, including a build number and a trailing `+` where the source carries them (`2025.4.10333+`, not `2025.4`). Rounding a boundary, or inventing one that the source does not state, is a fabricated technical specific — the highest-severity defect in these standards (see `content-conventions.md`). + +An entry MAY: + +- Carry more than one version boundary for a single subject, where a capability lands on parallel release trains at different builds (for example, a fix present in both a maintained line and the current line). List each boundary the subject applies to. + +## Relevance + +A version note SHOULD be included only while its boundary is still relevant to readers who run self-hosted Octopus. A caveat keyed to a version older than anyone still runs adds a line no reader needs, which works against the reason the element exists. + +These standards do not define a version floor. Relevance is a matter of author judgment: an author keeps a note while it still serves self-hosted readers and drops it when it no longer does. This is not mechanically enforceable, and the validation check does not prune stale notes. + +## Format + +Use the shape that stays scannable for the number of entries: + +- A bulleted list when there are few entries. +- A table with the subject as the first column once several entries accumulate. The subject-first column keeps every row self-describing. + +## Examples + +A well-formed version notes block as a list: + +> ## Version notes +> +> - Viewing build information under Deploy ➜ Manage ➜ Build Information is available from Octopus Server 2019.10.0. +> - Viewing build information on deployments is available from 2024.2. +> - Kubernetes manifest reporting via the `kubectl` helper functions is available in 2025.4.10333+ and 2026.1.4557+. + +This is well-formed because each entry names its own subject, keys to a self-hosted version, records the version strings exactly as the source states them (including the build numbers and `+` on the Kubernetes entry), and the one entry that lands on two release trains lists both boundaries. + +The same content as a table, once the list has grown enough to warrant one: + +> ## Version notes +> +> | Capability | Availability | +> |---|---| +> | Build information page (Deploy ➜ Manage ➜ Build Information) | From 2019.10.0 | +> | Build information on deployments | From 2024.2 | +> | Kubernetes manifest reporting (`kubectl` helpers) | 2025.4.10333+, 2026.1.4557+ | + +A well-formed removal entry: + +> - The `Octopus.Features` setting that toggled the legacy portal was removed in 2023.2; from that version the setting has no effect and can be deleted. + +A well-formed behavior-change entry: + +> - Before 2022.3, deleting an environment left its variable scopes in place; from 2022.3 the scopes are removed with the environment. + +Each names the subject, the boundary, and what changed at it. + +A poorly-formed version notes block: + +> ## Version notes +> +> - Available from 2024.2. +> - Now works on Cloud. +> - Build information is available from around 2019 or so. +> - All values are returned as strings. + +This is poorly-formed because: + +- The first entry names no subject; lifted out of the prose it is unreadable. +- The second is keyed to Cloud, which always runs the latest release and never carries a version caveat. +- The third rounds the boundary ("around 2019 or so") instead of recording the exact version the source states — an invented technical specific. +- The fourth is not version-specific at all. It is a caveat true across every version and belongs inline where it applies, not in this block. + +## Template + +``` +## Version notes <!-- optional; self-hosted versions only; last body element, before Related links --> +- [Subject] is available from [exact self-hosted version]. +- [Subject] was removed in [exact self-hosted version]; [what is true from that version]. +- Before [exact self-hosted version], [subject] [old behavior]; from [that version], [new behavior]. +``` diff --git a/cspell.json b/cspell.json index f88ac75301..02f597d725 100644 --- a/cspell.json +++ b/cspell.json @@ -58,6 +58,7 @@ "package-lock.yaml", "pnpm-lock.yaml", "docs/credits.md", + "contributing/standards/**", ".octopus/**", ".vscode/**", ".github/**", From 081e6cb86b1cf08c9faec7f6f69c122df615d8cc Mon Sep 17 00:00:00 2001 From: Sam Irons <sam.irons@octopus.com> Date: Mon, 31 Aug 2026 15:13:41 +1000 Subject: [PATCH 2/4] Add a routing README for the content standards The ten standards say what each page type requires, but nothing in the folder said which one to reach for. That guidance existed only in the skill's SKILL.md, so contributors not using Claude Code had an alphabetical file list and no way in. Move the dual-audience parts of SKILL.md here and make this the canonical copy: the content model, choosing a page type from the reader's main job, the guide-versus-tutorial boundary, and the routing table. Named README.md so GitHub renders it as the folder index. Routing and orientation only. It never restates substance from the ten standards, so a stale README can at worst misroute someone to a file that is still correct. The rebuilt skill should point at this file rather than restate any of it, otherwise the routing logic has two copies and we are back to the drift this move was meant to end. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --- contributing/standards/README.md | 85 ++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 contributing/standards/README.md diff --git a/contributing/standards/README.md b/contributing/standards/README.md new file mode 100644 index 0000000000..901430431e --- /dev/null +++ b/contributing/standards/README.md @@ -0,0 +1,85 @@ +# Documentation content standards + +This folder is the source of truth for how Octopus documentation is structured. The `octopus-docs-standards` Claude Code skill and the internal Confluence guidance both point back to these files. + +The standards define a typed content model: small typed *topics* compose into typed *page deliverables*. Structure is specified rather than left to each author's judgment, and that specification is what keeps the docs set consistent and findable. So don't write a page from intuition about what a good docs page looks like. Work out which type you're writing, then follow the standards for that type. + +These standards govern **structure** — what elements a page contains, and in what order. For voice, tone, spelling, and formatting, see the [Octopus style guide](https://www.octopus.design/latest/brand/writing/overview-VLYeW2mi-VLYeW2mi). The two are complementary: the standards decide what's on the page, the style guide decides how the prose reads. + +## The content model + +There are two layers: + +- **Topics** are the reusable units, and each one does a single job. A concept topic explains an idea. A task topic gives the steps for one action. A reference topic holds structured lookup data. +- **Page deliverables** are what ships at a URL, assembled from topics. There are four: concept, guide, reference, and tutorial pages. More will be added as their standards are agreed. + +A topic rendered inside a page becomes one of that page's H2 sections. A topic that ships on its own at its own URL is itself a page deliverable, and carries frontmatter like any other page. + +## Which page type am I writing? + +The page type follows from the reader's main job on the page. It isn't decided by the subject matter, and it isn't decided by the title. + +| The reader wants to | Write a | +| --- | --- | +| Understand a model — how the parts fit together, why they exist | Concept page | +| Complete a procedure | Guide page | +| Look up values — options, settings, commands, variables | Reference page | +| Learn by doing, working through one supplied example end to end | Tutorial page | + +If a page seems to need to be two of these, it's usually two pages. Open the candidate standard before you commit to one: each opens by stating what that page type is and is not. + +### Guide or tutorial? + +This is the easy one to get wrong, because both are built out of procedures. A tutorial is not "a guide for beginners". The question to ask is *whose goal, and whose example?* + +A guide serves a reader who arrives with their own job to do and their own values to plug in, and it may branch to cover their situation. A tutorial supplies both the goal and the example, runs a single guaranteed path with no branching, and exists to teach — success is the reader reaching the end, not solving a problem they brought with them. + +So if the page invents the goal and hands the reader concrete values to follow, it's a tutorial. If the reader brings both, it's a guide. [tutorial-page.md](tutorial-page.md) opens by setting out this boundary in full. + +## Which standards apply + +Read the standards for **both** the page and the topics it's assembled from. The page standard governs assembly and ordering; the topic standards govern what goes inside each section. Reading one without the other misses half the rules. + +| Writing or editing | Read | +| --- | --- | +| A concept page | [concept-page.md](concept-page.md) and [concept-topic.md](concept-topic.md), plus [reference-topic.md](reference-topic.md) if the page includes reference data | +| A guide page | [guide-page.md](guide-page.md) and [task-topic.md](task-topic.md), plus [concept-topic.md](concept-topic.md) if it opens with a concept introduction, and [reference-topic.md](reference-topic.md) if it includes reference data | +| A reference page | [reference-page.md](reference-page.md) and [reference-topic.md](reference-topic.md) | +| A tutorial page | [tutorial-page.md](tutorial-page.md), [concept-topic.md](concept-topic.md), and [task-topic.md](task-topic.md) | +| A single topic that ships standalone | the matching topic standard for its type | + +Two of the standards are cross-cutting, so they don't appear in the table: + +- [content-conventions.md](content-conventions.md) applies to every authoring, editing, and review task. +- [frontmatter.md](frontmatter.md) applies to anything that ships at its own URL — every page, and any topic published standalone. + +A third is conditional. [version-notes.md](version-notes.md) applies when a page carries version-specific caveats, and it covers concept, guide, and reference pages only — not tutorials. + +## The standards + +Ordered by the content model rather than alphabetically, because the layering is the point. + +Topics: + +- [concept-topic.md](concept-topic.md) +- [task-topic.md](task-topic.md) +- [reference-topic.md](reference-topic.md) + +Pages: + +- [concept-page.md](concept-page.md) +- [guide-page.md](guide-page.md) +- [reference-page.md](reference-page.md) +- [tutorial-page.md](tutorial-page.md) + +Cross-cutting: + +- [frontmatter.md](frontmatter.md) +- [content-conventions.md](content-conventions.md) +- [version-notes.md](version-notes.md) + +## Using these with Claude Code + +You don't have to apply these standards by hand. The `octopus-docs-standards` skill reads them for you and applies them as you draft or review, and `octopus-writing-guide` covers voice and style alongside it. See [CONTRIBUTING.md](../../CONTRIBUTING.md) for how to get set up and how to work with the agent. + +This page stays the source of truth either way — the skill routes from these files rather than carrying its own copy of them. From a0f0bfbd17c567023e4791d6c9d93fd8d4c0c88e Mon Sep 17 00:00:00 2001 From: Sam Irons <sam.irons@octopus.com> Date: Mon, 31 Aug 2026 15:16:04 +1000 Subject: [PATCH 3/4] Drop the forward-looking claim about how the skill loads the standards The line described the rebuilt skill's behavior, which isn't true until that rebuild ships. The rest of the section already tells contributors what they need without asserting anything about the skill's internals. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --- contributing/standards/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/contributing/standards/README.md b/contributing/standards/README.md index 901430431e..e198f88c95 100644 --- a/contributing/standards/README.md +++ b/contributing/standards/README.md @@ -81,5 +81,3 @@ Cross-cutting: ## Using these with Claude Code You don't have to apply these standards by hand. The `octopus-docs-standards` skill reads them for you and applies them as you draft or review, and `octopus-writing-guide` covers voice and style alongside it. See [CONTRIBUTING.md](../../CONTRIBUTING.md) for how to get set up and how to work with the agent. - -This page stays the source of truth either way — the skill routes from these files rather than carrying its own copy of them. From f437099b40158286e489852babd77b29760c0dbc Mon Sep 17 00:00:00 2001 From: Sam Irons <sam.irons@octopus.com> Date: Mon, 31 Aug 2026 15:31:45 +1000 Subject: [PATCH 4/4] Clarify that the skill fed by these standards is internal Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --- contributing/standards/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/standards/README.md b/contributing/standards/README.md index e198f88c95..5835332e5e 100644 --- a/contributing/standards/README.md +++ b/contributing/standards/README.md @@ -1,6 +1,6 @@ # Documentation content standards -This folder is the source of truth for how Octopus documentation is structured. The `octopus-docs-standards` Claude Code skill and the internal Confluence guidance both point back to these files. +This folder is the source of truth for how Octopus documentation is structured. For internal contributors, this is also the source of truth for our internal `octopus-docs-standards` Claude Code skill. The standards define a typed content model: small typed *topics* compose into typed *page deliverables*. Structure is specified rather than left to each author's judgment, and that specification is what keeps the docs set consistent and findable. So don't write a page from intuition about what a good docs page looks like. Work out which type you're writing, then follow the standards for that type.