Elastic docs v3 edits (#259)

Author: lcawl

docs/source/migration/engineering.md

@@ -6,15 +6,16 @@ title: Reference docs guidelines
 
 As part of the transition to Elastic Docs v3, responsibility for maintaining reference documentation will reside with Engineering teams so that code and corresponding documentation remain tightly integrated, allowing for easier updates and greater accuracy.
 
-After migration, all narrative and instructional documentation actively maintained by writers will move to the elastic/docs-content repository. Reference documentation, such as API specifications, will remain in the respective product repositories so that Engineering teams can manage both the code and its related documentation in one place.
+After migration, all narrative and instructional documentation actively maintained by writers will move to the [elastic/docs-content](https://github.com/elastic/docs-content) repository. Reference documentation, such as API specifications, settings, and language references, will remain in the respective product repositories so that Engineering teams can manage both the code and its related documentation in one place.
 
 ## API documentation guidelines
 
 To improve consistency and maintain high-quality reference documentation, all API documentation must adhere to the following standards:
 
-* **Switch to OAS (OpenAPI specification)**: Engineering teams should stop creating AsciiDoc-based API documentation. All API documentation should now use OAS files, alongside our API documentation that lives at elastic.co/docs/api.
-* **Comprehensive API descriptions**: Ensure that OAS files include:
+* **OpenAPI source files**: Engineering teams should stop creating AsciiDoc-based API documentation. All API documentation will be derived from OpenAPI documents and published on [elastic.co/docs/api](https://www.elastic.co/docs/api/).
+* **Accurate and complete content**: OpenAPI documents must include:
   * API descriptions
-  * Request descriptions
-  * Response descriptions
-* **Fix linting warnings**: Address all new and existing linting warnings in OAS files to maintain clean and consistent documentation.
+  * Request, response, parameter, and property descriptions
+  * Valid examples
+* **Stylistically consistent content**: Refer to API guidelines for consistency (reach out to #docs team for the current internal link).
+* **Automatically linted**: Use the shared linting rules and address all new and existing linting warnings to maintain clean and consistent documentation.

docs/source/migration/freeze/gh-action.md

@@ -3,7 +3,8 @@ title: GH Action
 ---
 
 ## Overview
-This GitHub Action enforces documentation freezes by adding comments to pull requests that modify `.asciidoc` files. It complements the use of `CODEOWNERS` to ensure changes during a freeze period are reviewed and approved by the `@docs-freeze-team`.
+
+The documentation team will use a GitHub Action to enforce the content freeze by adding comments to pull requests that modify `.asciidoc` files. It complements the use of `CODEOWNERS` to ensure changes during a freeze period are reviewed and approved by the `@docs-freeze-team`.
 
 ## How It Works
 1. **Trigger**: The Action is triggered on pull request events (`opened`, `reopened`, or `synchronize`).

docs/source/migration/freeze/index.md

@@ -2,7 +2,7 @@
 title: Documentation Freeze
 ---
 
-During the documentation freeze, the Docs team will focus almost entirely on migration tasks to ensure all content is successfully migrated and will handle only emergency documentation requests and release-related activities. When the migration is complete, writers will address documentation requests needed during the documentation freeze, ensuring that updates align with the new information architecture and format.
+During the documentation freeze, the Docs team will focus almost entirely on migration tasks to ensure all content is successfully migrated and will handle only emergency documentation requests and release-related activities. When the migration is complete, the docs team will assess any documentation requests that were submitted during the documentation freeze and ensure that they're still relevant in the new information architecture and format.
 
 To make the transition to Elastic Docs v3 as smooth as possible, we’ve established a process to track and manage documentation requests during the migration:
 

docs/source/migration/ia.md

@@ -9,8 +9,8 @@ The new IA design does the following:
 
 * Provides a clear narrative pathway for users to follow, including new topics that compare similar technologies and features.
 * Organizes content by user goal and role.
-* Consolidates content previously duplicated across our books, including serverless and stateful content, and many tasks that are common across deployment types and solutions.
-* Explains the context a topic applies to (deployment type, version) - see Consolidated versioning below for more information.
+* Consolidates content previously duplicated across our books, including cloud hosted, serverless, and stack content, and many tasks that are common across deployment types and solutions.
+* Explains the context a topic applies to (deployment type, version). Check out [Consolidated versioning](versioning.md) for more information.
 * Separates reference content into its own section for easy access.
 
 To learn more:

docs/source/migration/index.md

@@ -6,7 +6,7 @@ navigation_title: Migration
 We are ready to migrate our documentation to our new build system, [elastic/docs-builder](https://github.com/elastic/docs-builder)!
 
 :::{important}
-We will enforce a [Documentation Freeze](./freeze/index.md) while we migration docs between our two build systems.
+We will enforce a [Documentation Freeze](./freeze/index.md) while we migrate docs between our two build systems.
 :::
 
 Migrating to Elastic Docs V3 is more than just moving to a new documentation build system. This migration also includes:

docs/source/migration/syntax.md

@@ -3,7 +3,7 @@ title: New syntax
 navigation_title: New syntax
 ---
 
-With the migration to Elastic Docs v3, the primary format for all Elastic Docs is transitioning from AsciiDoc to Markdown. Why Markdown? Markdown is already an industry standard across the industry, and 90% of Elastic developers are comfortable working with Markdown syntax [[source](https://docs.google.com/presentation/d/1morhFX4tyVB0A2f1_fnySzeJvPYf0kXGjVVYU_lVRys/edit#slide=id.g13b75c8f1f3_0_463)].
+With the migration to Elastic Docs v3, the primary format for all Elastic Docs is transitioning from AsciiDoc to Markdown. Why Markdown? Markdown is already an industry standard and 90% of Elastic developers are comfortable working with Markdown syntax [[source](https://docs.google.com/presentation/d/1morhFX4tyVB0A2f1_fnySzeJvPYf0kXGjVVYU_lVRys/edit#slide=id.g13b75c8f1f3_0_463)].
 
 See our [syntax guide](../syntax/index.md) to learn more about the flavor of Markdown that we support.
 

docs/source/migration/versioning.md

@@ -9,4 +9,4 @@ To ensure a seamless experience for users and contributors, the new versioning a
 * Context awareness — Each page explicitly states the context it applies to, including relevant deployment types (e.g., Elastic Cloud Hosted and Elastic Cloud Serverless) and versions. Context clarity ensures users know if the content is applicable to their environment. When users land on a Docs page that doesn’t apply to their version or deployment type, clear cues and instructions will guide them to the appropriate content.
 * Simplified contributor workflow — For pages that apply to multiple versions or deployment types, we’ve optimized the contributor experience by reducing complexity. Contributors can now manage multi-context content with ease, without duplicating information or navigating confusing workflows.
 
-For versioning plan details, check [Docs Versioning plan](https://docs.google.com/presentation/d/1fX8YBGcFlHJPi1kVfB9tC-988iUvxZJAZiH21kE4A5M/edit#slide=id.g319e4ce75b5_0_0). To learn how to call out versioning differences in docs-builder, see [product availability](../syntax/applies.md).
+For versioning plan details, check [Docs Versioning plan](https://docs.google.com/presentation/d/1rHl0ia0ZkLHPLAYE5522CTDoatqwAxwAo29_etStPW8/edit?usp=sharing). To learn how to call out versioning differences in docs-builder, see [product availability](../syntax/applies.md).