[docs] clean up after migrating some contributions, syntax guide

leemthompo · leemthompo · commit b57bd9fd8f9e · 2025-11-05T18:22:02.000+01:00
diff --git a/docs/_docset.yml b/docs/_docset.yml
@@ -29,20 +29,19 @@ toc:
   - file: index.md
   - hidden: 404.md
   - hidden: developer-notes.md
-  - folder: contribute
+  - hidden: contribute/index.md
+  - hidden: contribute/locally.md
+  - hidden: contribute/on-the-web.md
+  - hidden: contribute/cumulative-docs/index.md
+  - hidden: contribute/cumulative-docs/guidelines.md
+  - hidden: contribute/cumulative-docs/badge-placement.md
+  - hidden: contribute/cumulative-docs/example-scenarios.md
+  - hidden: contribute/cumulative-docs/reference.md
+  - folder: how-to
     children:
       - file: index.md
-      - file: locally.md
-      - file: on-the-web.md
       - file: move.md
       - file: redirects.md
-      - folder: cumulative-docs
-        children:
-          - file: index.md
-          - hidden: guidelines.md
-          - hidden: badge-placement.md
-          - hidden: example-scenarios.md
-          - hidden: reference.md
       - file: branching-strategy.md
       - file: add-repo.md
       - file: release-new-version.md
diff --git a/docs/_redirects.yml b/docs/_redirects.yml
@@ -24,3 +24,8 @@ redirects:
   'testing/redirects/third-page.md':
     anchors:
       'removed-anchor':
+  'contribute/move.md': 'how-to/move.md'
+  'contribute/redirects.md': 'how-to/redirects.md'
+  'contribute/branching-strategy.md': 'how-to/branching-strategy.md'
+  'contribute/add-repo.md': 'how-to/add-repo.md'
+  'contribute/release-new-version.md': 'how-to/release-new-version.md'
diff --git a/docs/building-blocks/assembled-documentation.md b/docs/building-blocks/assembled-documentation.md
@@ -19,7 +19,7 @@ The assembler:
 
 Assembled documentation is configured through the site configuration, which defines:
 
-* [assembler.yml](../configure/site/index.md): Which repositories to include and [their branching strategy](../contribute/branching-strategy.md).
+* [assembler.yml](../configure/site/index.md): Which repositories to include and [their branching strategy](../how-to/branching-strategy.md).
 * [navigation.yml](../configure/site/index.md): Navigation and url prefixes for TOC's.
 * [versions.yml](../configure/site/versions.md): Defines the various versioning schemes of products/solutions being documented.
 * [products.yml](../configure/site/products.md): Defines the product catalog (id, name) and ties it to a specific versioning scheme.
diff --git a/docs/building-blocks/index.md b/docs/building-blocks/index.md
@@ -1,8 +1,8 @@
 ---
-navigation_title: Building blocks
+navigation_title: Core architecture concepts
 ---
 
-# Building blocks
+# Core architecture concepts and building blocks
 
 This section explains the core concepts and building blocks that make up the docs-builder architecture. Understanding these concepts will help you work effectively with distributed documentation and cross-repository linking.
 
diff --git a/docs/cli/docset/diff-validate.md b/docs/cli/docset/diff-validate.md
@@ -4,7 +4,7 @@ Gathers the local changes by inspecting the git log, stashed and unstashed chang
 
 It currently validates the following:
 
-* Ensures that renames and deletions are reflected in [redirects.yml](../../contribute/redirects.md).
+* Ensures that renames and deletions are reflected in [redirects.yml](../../how-to/redirects.md).
 
 ## Usage
 
diff --git a/docs/cli/docset/index.md b/docs/cli/docset/index.md
@@ -22,5 +22,5 @@ locate the `docset.yml` anywhere in the directory tree automatically and build t
 ## Refactor commands
 
 - [mv](mv.md) - move a file or folder to a new location. This will rewrite all links in all files too.
-- [diff validate](diff-validate.md) - validate that local changes are reflected in [redirects.yml](../../contribute/redirects.md)
+- [diff validate](diff-validate.md) - validate that local changes are reflected in [redirects.yml](../../how-to/redirects.md)
 
diff --git a/docs/configure/site/index.md b/docs/configure/site/index.md
@@ -14,7 +14,7 @@ Configure the documentation site in these files:
 
 ## Redirects
 
-Redirects are also configured at the site-level. See [](../../contribute/redirects.md) for more information.
+Redirects are also configured at the site-level. See [](../../how-to/redirects.md) for more information.
 
 ## Synonyms
 
diff --git a/docs/contribute/_snippets/tagged-warning.md b/docs/contribute/_snippets/tagged-warning.md
@@ -1,7 +1,7 @@
 :::{warning}
-Some repositories use a [tagged branching strategy](/contribute/branching-strategy.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.
+Some repositories use a [tagged branching strategy](/how-to/branching-strategy.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 branching strategy for a repository](/contribute/branching-strategy.md#workflow-2-tagged).
+For detailed backporting guidance, refer to the example in [Choose the docs branching strategy for a repository](/how-to/branching-strategy.md#workflow-2-tagged).
 
 To determine the published branches for a repository, find the repository in [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml).
 :::
diff --git a/docs/contribute/index.md b/docs/contribute/index.md
@@ -1,4 +1,5 @@
-# Elastic Docs contribution guide
+
+# Contribute to docs
 
 :::{note}
 👋 This page has moved to [elastic.co/docs](https://www.elastic.co/docs/contribute-docs/).
diff --git a/docs/how-to/add-repo.md b/docs/how-to/add-repo.md
@@ -1,3 +1,7 @@
+---
+navigation_title: "Add a new repo to the docs"
+---
+
 # Add a new repository to the docs
 
 Elastic documentation is built from many assembled repositories using `docs-builder assemble`. Adding a new repository requires making the assembly process aware of its existence.
@@ -55,7 +59,7 @@ references:
 ```
 
 :::{tip}
-In this file, you can optionally specify custom branches to deploy docs from, depending on your preferred [branching strategy](/contribute/branching-strategy.md). You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
+In this file, you can optionally specify custom branches to deploy docs from, depending on your preferred [branching strategy](/how-to/branching-strategy.md). You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
 :::
 
 Then, edit the [`navigation.yml`](https://github.com/elastic/docs-builder/blob/main/config/navigation.yml) file to add the repository to the navigation. Refer to [navigation.yml](../configure/site/navigation.md) for more information.
diff --git a/docs/how-to/branching-strategy.md b/docs/how-to/branching-strategy.md
@@ -1,5 +1,5 @@
 ---
-navigation_title: Choose a branching strategy
+navigation_title: Choose a repo branch strategy
 ---
 
 # Choose the docs branching strategy for a repository
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
@@ -0,0 +1,21 @@
+# How-to guides
+
+:::{tip}
+Looking for contribution guides on how to write the docs? Refer to [Contribute to docs](https://www.elastic.co/docs/contribute-docs/) on the main Elastic documentation site.
+:::
+
+Use these guides for tasks like managing documentation files and folders, configuring repositories, and handling releases.
+
+## Manage files and links
+
+- [Move files and folders](move.md): Move files or folders and automatically update all links in the documentation.
+- [Manage redirects across doc sets](redirects.md): Set up redirects when moving or deleting pages to prevent broken links.
+
+## Repository management
+
+- [Add a new repository to the docs](add-repo.md): Add a new docs repository to the assembly process.
+- [Choose a branching strategy](branching-strategy.md): Choose the right docs branching strategy for your repository.
+
+## Release management
+
+- [Release a new documentation version](release-new-version.md): Update the docs site when a new version of the Elastic Stack or other versioned product is released.
diff --git a/docs/how-to/move.md b/docs/how-to/move.md
diff --git a/docs/how-to/redirects.md b/docs/how-to/redirects.md
@@ -1,5 +1,5 @@
 ---
-navigation_title: "Redirects"
+navigation_title: "Set up redirects"
 ---
 
 # Manage redirects across doc sets
diff --git a/docs/how-to/release-new-version.md b/docs/how-to/release-new-version.md
@@ -1,3 +1,7 @@
+---
+navigation_title: Release a new docs version
+---
+
 # Release a new documentation version
 
 When a new version of the Elastic Stack (or another versioned product) is released, the docs site must be updated to recognize it. This process primarily involves updating version metadata in the shared site configuration.
diff --git a/docs/migration/versioning.md b/docs/migration/versioning.md
@@ -19,5 +19,5 @@ In this new system, documentation is written **cumulatively**. This means that a
 
 In Docs V3, a single branch is published per repository. This branch is set to `main` by default, but it is possible to instead publish a different branch by changing your repository's branching strategy. You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
 
-* [Learn how to choose the right branching strategy for your repository](/contribute/branching-strategy.md)
+* [Learn how to choose the right branching strategy for your repository](/how-to/branching-strategy.md)
 * [Learn how to set up your selected branching strategy](/configure/content-sources.md)
