more fixes

shainaraskas · shainaraskas · commit d2aac67feef1 · 2025-06-25T15:35:28.000-04:00
diff --git a/docs/_docset.yml b/docs/_docset.yml
@@ -13,6 +13,8 @@ subs:
   serverless-short: Serverless
   ece:   "Elastic Cloud Enterprise"
   eck:   "Elastic Cloud on Kubernetes"
+  ech:  "Elastic Cloud Hosted"
+  serverless-full: "Elastic Cloud Serverless"
 
 features:
   primary-nav: false
@@ -33,7 +35,6 @@ toc:
       - file: redirects.md
       - file: cumulative-docs.md
       - file: deployment-models.md
-      - file: releasing.md
   - folder: migration
     children:
       - file: index.md
diff --git a/docs/contribute/_snippets/docs-intro.md b/docs/contribute/_snippets/docs-intro.md
@@ -0,0 +1,5 @@
+elastic.co/docs uses our new build system, also known as "Docs V3", which uses an extended version of markdown as its markup language. Refer to our [syntax guide](syntax.md) to learn more.
+
+Docs for {{stack}} 9.x, {{ece}} 4.x, and {{eck}} 3.x can all be found on this site. All unversioned products, such as {{ech}} and {{serverless-full}}, are also documented on elastic.co/docs.
+
+This documentation is **cumulative**. This means that a new set of docs is not published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes directly within the content. [Learn how to write cumulative documentation](cumulative-docs.md).
diff --git a/docs/contribute/_snippets/guide-intro.md b/docs/contribute/_snippets/guide-intro.md
@@ -0,0 +1,3 @@
+To contribute to elastic.co/guide, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses ASCIIDoc as its markup language.
+
+Docs for {{stack}} 8.x, {{ece}} 3.x, and {{eck}} 2.x can all be found on this site.
diff --git a/docs/contribute/_snippets/tagged-warning.md b/docs/contribute/_snippets/tagged-warning.md
@@ -0,0 +1,7 @@
+:::{caution}
+Some repositories use a [tagged deployment model](deployment-models.md), which means that their docs are published from a branch that is not `main` or `master`. In these cases, documentation changes need to be made to `main` or `master`, and then backported to the relevant branches.
+
+For detailed backporting guidance, refer to the example in [Choose the docs deployment model for a repository](/contribute/deployment-models.md#workflow-2-make-docs-updates-when-the-repo-is-publishing-docs-from-a-version-branch).
+
+To determine the published branches for a repository, find the repository in [assembler.yml](https://github.com/elastic/docs-builder/blob/main/src/tooling/docs-assembler/assembler.yml).
+:::
diff --git a/docs/contribute/_snippets/two-systems.md b/docs/contribute/_snippets/two-systems.md
@@ -0,0 +1,7 @@
+The way that you contribute to the docs depends on the product version.
+
+For a list of versions covered on [elastic.co/docs](https://www.elastic.co/docs), refer to [Find docs for your product version](/get-started/versioning-availability.md#find-docs-for-your-product-version). Versions prior to the versions listed on that page are documented on our legacy system, [elastic.co/guide](https://www.elastic.co/guide). 
+
+:::{tip}
+Unversioned products, such as {{ech}} and {{serverless-full}}, are documented on [elastic.co/docs](https://www.elastic.co/docs).
+:::
diff --git a/docs/contribute/deployment-models.md b/docs/contribute/deployment-models.md
@@ -34,9 +34,12 @@ Once it’s been established that a repository should publish from a version bra
    * Specify which is the `current` branch for the repository. This branch is the branch from which docs are deployed to production at [elastic.co/docs](http://elastic.co/docs).  
    * Specify which is the `next` branch for the repository. The branch defined as `next` publishes docs internally to [staging-website.elastic.co/docs](http://staging-website.elastic.co/docs)  
      * Setting this branch to the next version branch in line is a good practice to preview docs change for an upcoming version.  
-     * Otherwise, keeping it set to `main` is also an option since this is where the content is initially developed and merged. This is the default.  
-2. Add an action as part of that repo’s release process for the release manager to update this same assembler file and bump the `current` branch with each release, as appropriate.  
-3. When these releases happen, create a PR against this file that defines the new `current` branch, to merge on release day.
+     * Otherwise, keeping it set to `main` is also an option since this is where the content is initially developed and merged. This is the default.
+2. [Add new triggers to the `docs-build` CI integration](/configure/deployment-models.md#ci-configuration).  
+3. Add an action as part of that repo’s release process for the release manager to update this same assembler file and bump the `current` branch with each release, as appropriate.  
+4. When these releases happen, create a PR against this file that defines the new `current` branch, to merge on release day.
+
+For more information, refer to [](/configure/deployment-models.md).
 
 ## Workflow 1 (default): Make docs updates when the repo is publishing docs from `main`
 
@@ -56,7 +59,7 @@ When a repo publishes docs from its `main` branch, any merged changes are publis
 | --- | --- | --- |
 | 1 | You are documenting changes for an unversioned product (typically Serverless or Elastic Cloud), and the changes should only go live when the corresponding code or feature is available to users | The PR should be merged on or after the release date of the feature. |
 | 2 | You are documenting changes for a versioned product (any Stack components, ECE, ECK, etc.).<br><br>We have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as `Planned`. | You have the choice between merging the PR as soon as it is approved, or merging it only on release day. |
-| You are documenting changes that apply to both versioned and unversioned products (typically a change that is being released for both Serverless and an upcoming Stack release), you are in the same situation as Case 1. | The PR should only be merged on or after the release date of the feature in Serverless. Note that for versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as `Planned`. |
+| 3 | You are documenting changes that apply to both versioned and unversioned products (typically a change that is being released for both Serverless and an upcoming Stack release), you are in the same situation as Case 1. | The PR should only be merged on or after the release date of the feature in Serverless. Note that for versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as `Planned`. |
 
 When a repo is publishing docs from its `main` branch, no backporting is needed.
 
@@ -88,7 +91,7 @@ The changes must then be backported to their relevant version branches, and no f
 | --- | --- | --- |
 | 1 | You are documenting changes for an unversioned product (typically Serverless or Elastic Cloud), the changes should go live when the corresponding code or feature is available to users. | The PR should be backported to the docs `current` branch, and any intermediate version branches that already exist between `current` and `main`. Merge the backport PR for `current` only when you’re sure the corresponding feature is released. |
 | 2 | You are documenting changes for a versioned product (any Stack components, ECE, ECK, etc.).<br><br>We have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as “Planned”. | Backport the PR to the relevant version branch and to any intermediate version branch that already exists. The changes will go live whenever these branches become the `current` docs branch. |
-| 3 | you are documenting changes that apply to both versioned and unversioned products (typically a change that is being released for both Serverless and an upcoming Stack release), you are in the same situation as Case 1. | The PR should be backported to the docs `current` branch, and any intermediate version branches that already exist between `current` and `main`. Merge the backport PR for `current` only when you’re sure the corresponding feature is released. <br><br>Note that for versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as `Planned`. |
+| 3 | You are documenting changes that apply to both versioned and unversioned products (typically a change that is being released for both Serverless and an upcoming Stack release), you are in the same situation as Case 1. | The PR should be backported to the docs `current` branch, and any intermediate version branches that already exist between `current` and `main`. Merge the backport PR for `current` only when you’re sure the corresponding feature is released. <br><br>Note that for versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as `Planned`. |
 
 #### Example 
 
diff --git a/docs/contribute/index.md b/docs/contribute/index.md
@@ -12,32 +12,23 @@ Whether you're a technical writer or you've only edited Elastic docs once or twi
 
 In April 2025, we released our new documentation site. This site includes documentation for our latest product versions, including {{stack}} 9.0+ and {{serverless-full}}.
 
-The way that you contribute to the docs depends on the product version.
-
-For a list of versions covered on [elastic.co/docs](https://www.elastic.co/docs), refer to [Find docs for your product version](/get-started/versioning-availability.md#find-docs-for-your-product-version). Versions previous to the versions listed on that page are documented on our legacy system, [elastic.co/guide](https://www.elastic.co/guide). 
-
-:::{tip}
-Unversioned products, such as {{ech}} and {{serverless-full}}, are documented on [elastic.co/docs](https://www.elastic.co/docs).
+:::{include} _snippets/two-systems.md
 :::
 
 ### Contribute to elastic.co/guide
 
-To contribute to elastic.co/guide, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses ASCIIDoc as its markup language.
-
-Docs for {{stack}} 8.x, {{ece}} 3.x, and {{eck}} 2.x can all be found on this site.
+:::{include} _snippets/guide-intro.md
+:::
 
 * For **simple bug fixes and enhancements**: [Contribute on the web](on-the-web.md)
 * For **complex or multi-page updates**: See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation)
 
 ### Contribute elastic.co/docs
 
-elastic.co/docs uses our new build system, also known as "Docs V3", which uses an extended version of markdown as its markup language. Refer to our [syntax guide](syntax.md) to learn more.
-
-Docs for {{stack}} 9.x, {{ece}} 4.x, and {{eck}} 3.x can all be found on this site. All unversioned products, such as {{ech}} and {{serverless-full}}, are also documented on elastic.co/docs.
-
-This documentation is **cumulative**. This means that a new set of docs is not published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes directly within the content. [Learn how to write cumulative documentation](cumulative-docs.md).
+:::{include} _snippets/docs-intro.md
+:::
 
-* For **simple bug fixes and enhancements**: [contribute on the web](on-the-web.md)
+* For **simple bug fixes and enhancements**: [Contribute on the web](on-the-web.md)
 * For **complex or multi-page updates**: [Contribute locally](locally.md)
 
 #### Branches in V3
diff --git a/docs/contribute/locally.md b/docs/contribute/locally.md
@@ -49,7 +49,7 @@ This guide uses the first option. If you'd like to clone the repository and buil
 
 2. **Run docs-builder from a docs folder**
 
-   Use the `serve` command from any docs folder to start serving the documentation at http://localhost:3000:
+   Use the `serve` command from any docs folder to start serving the documentation at [http://localhost:3000](http://localhost:3000):
 
    ```sh
    docs-builder serve
@@ -83,7 +83,7 @@ If you get a `Permission denied` error, make sure that you aren't trying to run
 
 2. **Run docs-builder from a docs folder**
 
-   Use the `serve` command from any docs folder to start serving the documentation at http://localhost:3000:
+   Use the `serve` command from any docs folder to start serving the documentation at [http://localhost:3000](http://localhost:3000):
 
    ```sh
    docs-builder serve
@@ -93,19 +93,19 @@ If you get a `Permission denied` error, make sure that you aren't trying to run
 ::::
 
 
-## Clone a content repository [#step-two]
+## Step 2: Clone a content repository [#step-two]
 
 :::{tip}
-Documentation lives in many repositories across Elastic. If you're unsure which repository to clone, you can use the "Edit this page" link on any documentation page to determine where the source file lives.
+Documentation is hosted in many repositories across Elastic. If you're unsure which repository to clone, you can use the **Edit this page** link on any documentation page to determine where the source file is hosted.
 :::
 
-In this guide, we'll clone the [`docs-content`](https://github.com/elastic/docs-content) repository. The `docs-content` repository is the home for narrative documentation at Elastic. Clone this repo to a directory of your choice:
+In this guide, we'll clone the [`docs-content`](https://github.com/elastic/docs-content) repository. The `docs-content` repository is the home for most narrative documentation at Elastic. Clone this repo to a directory of your choice:
 
 ```sh
 git clone https://github.com/elastic/docs-content.git
 ```
 
-## Serve the documentation [#step-three]
+## Step 3: Serve the documentation [#step-three]
 
 Static-site generators like docs-builder can serve docs locally. This means you can edit the source and see the result in the browser in real time.
 
@@ -122,7 +122,7 @@ cd docs-content
 
 :::::{step} Run docs-builder
 
-Run the `docs-builder` binary with the `serve` command to build and serve the content set to http://localhost:3000. If necessary, specify the path to the `docset.yml` file that you want to build with `-p`.
+Run the `docs-builder` binary with the `serve` command to build and serve the content set to [http://localhost:3000](http://localhost:3000). If necessary, specify the path to the `docset.yml` file that you want to build with `-p`.
 
 For example:
 
@@ -145,22 +145,27 @@ docs-builder serve -p .\migration-test
 :::::
 
 :::::{step} Open the documentation in the browser
-Now you should be able to view the documentation locally by navigating to http://localhost:3000.
+Now you should be able to view the documentation locally by navigating to [http://localhost:3000](http://localhost:3000).
 :::::
 ::::::
 
 ## Step 4: Write the docs [#step-four]
 
 We write docs in Markdown. Refer to our [syntax](../syntax/index.md) guide for the flavor of Markdown that we support and all of our custom directives that enable you to add a little extra pizzazz to your docs.
 
+This documentation is **cumulative**. This means that a new set of docs is not published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes directly within the content. [Learn how to write cumulative documentation](cumulative-docs.md).
+
+:::{include} tagged-warning.md
+:::
+
 ## Step 5: Push your changes [#step-five]
 
 After you've made your changes locally:
 
 * [Push your commits](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository)
 * [Open a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
 
-## Step 5: View the preview
+## Step 6: View the preview
 
 You can open a docs preview from the Deployments page of the repository. For example, [https://github.com/elastic/docs-content/deployments](https://github.com/elastic/docs-content/deployments).
 
diff --git a/docs/contribute/on-the-web.md b/docs/contribute/on-the-web.md
diff --git a/docs/contribute/releasing.md b/docs/contribute/releasing.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+To contribute to elastic.co/guide, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses ASCIIDoc as its markup language.`
	`2`	`+`
	`3`	`+Docs for {{stack}} 8.x, {{ece}} 3.x, and {{eck}} 2.x can all be found on this site.`