more cleanup

Author: bmorelli25

docs/source/docset.yml

@@ -31,12 +31,21 @@ toc:
   - folder: migration
     children:
       - file: index.md
-      - file: guide.md
-      - file: file-structure.md
-      - file: mapping.md
-      - file: tabs.md
-      - file: gh-action.md
-      - file: codeowner.md
+      - folder: freeze
+        children:
+          - file: index.md
+          - file: codeowner.md
+          - file: gh-action.md
+      - file: syntax.md
+      - file: ia.md
+      - file: versioning.md
+      - file: engineering.md
+      - folder: guide
+        children:
+          - file: index.md
+          - file: file-structure.md
+          - file: mapping.md
+          - file: migration-scripts.md
   - folder: configure
     children:
       - file: index.md

docs/source/index.md

@@ -6,11 +6,11 @@ Elastic Docs V3 is our next-generation documentation platform designed to improv
 
 **What do you want to do today?**
 
-* [Contribute to Elastic documentation](/contribute/index.html)
-* [Learn about migration to Elastic Docs V3](/migration/index.html)
-* [Configure content sets in V3](/configure/index.html)
-* [Learn about V3 syntax](/syntax/index.html)
-* [Contribute to V3 (developer guide)](/development/index.html)
+* [Contribute to Elastic documentation](./contribute/index.html)
+* [Learn about migration to Elastic Docs V3](./migration/index.html)
+* [Configure content sets in V3](./configure/index.html)
+* [Learn about V3 syntax](./syntax/index.html)
+* [Contribute to V3 (developer guide)](./development/index.md)
 
 ## About this repo
 

docs/source/migration/engineering.md

@@ -0,0 +1,20 @@
+---
+title: Reference docs guidelines
+---
+
+## Engineering ownership of reference documentation
+
+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.
+
+## 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:
+  * 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.

docs/source/migration/codeowner.md renamed to docs/source/migration/freeze/codeowner.md

@@ -1,13 +1,13 @@
 ---
-title: Documentation freeze CODEOWNERS
+title: Codeowner
 ---
 
 This document lists the CODEOWNERS configuration used to enforce documentation freezes across Elastic repositories. During a documentation freeze, the `@docs-freeze-team` must approve any pull requests that modify documentation files (`.asciidoc`) before they can be merged. This prevents unintended documentation changes during crucial periods such as releases.
 
 To regenerate this list, run the following commands from the repository root:
 
 ```sh
-cd docs/source/migration/scripts/codeowner-gen
+cd docs/source/migration/freeze/scripts/codeowner-gen
 python3 codeowner.py
 ```
 

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

@@ -1,5 +1,5 @@
 ---
-title: Documentation Freeze GH Action
+title: GH Action
 ---
 
 ## Overview

docs/source/migration/freeze/index.md

@@ -0,0 +1,12 @@
+---
+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.
+
+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:
+
+* Open an issue in [elastic/docs-content](https://github.com/elastic/docs-content/issues), including details about the documentation requirements, links to resources, and drafts of documentation in GDocs.
+* Post in [#docs](https://elastic.slack.com/archives/C0JF80CJZ) for emergency documentation requests.
+
+During the documentation freeze, maintaining consistency and avoiding conflicts is key. To prevent documentation changes from merging during the documentation freeze, [CODEOWNERS](./codeowner.md) and a [GH Action](./gh-action.md) are being added to /docs directories for public-facing documentation in all relevant repositories.