chore: Updates documentation structure to have data sources and resources in subcategories by feature #3629
Conversation
…explicit on deprecation
…ource/data sources
| @@ -1,5 +1,5 @@ | |||
| --- | |||
| subcategory: "Deprecated" | |||
| subcategory: "MongoDB Cloud Users" | |||
There was a problem hiding this comment.
aligning to statement defined in our PD: Deprecated resources and data sources will remain in their feature heading but with a clear label at the top of the page that the resource is deprecated (i.e. we will remove the separate “Deprecated” heading at the top level).
| --- | ||
|
|
||
| **WARNING:** This data source is deprecated and will be removed in January 2026. For more details, see [Migration Guide: Transition out of Serverless Instances and Shared-tier clusters](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/serverless-shared-migration-guide). | ||
| ~> **DEPRECATION:** This data source is deprecated and will be removed in January 2026. For more details, see [Migration Guide: Transition out of Serverless Instances and Shared-tier clusters](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/serverless-shared-migration-guide). |
There was a problem hiding this comment.
small formatting adjustment aligning all deprecated resources/data sources, ~> ** stands out much more
|
|
||
|
|
||
| ~> **IMPORTANT:** We recommend all new MongoDB Atlas Terraform users start with the [`mongodbatlas_advanced_cluster`](advanced_cluster) resource. Key differences between [`mongodbatlas_cluster`](cluster) and [`mongodbatlas_advanced_cluster`](advanced_cluster) include support for [Multi-Cloud Clusters](https://www.mongodb.com/blog/post/introducing-multicloud-clusters-on-mongodb-atlas), [Asymmetric Sharding](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema), and [Independent Scaling of Analytics Node Tiers](https://www.mongodb.com/blog/post/introducing-ability-independently-scale-atlas-analytics-node-tiers). For existing [`mongodbatlas_cluster`](cluster) resource users see our [Migration Guide](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/cluster-to-advanced-cluster-migration-guide). | ||
| ~> **DEPRECATION:** This resource is deprecated and will be removed in the next major release. Please use `mongodbatlas_advanced_cluster`. For more details, see [our migration guide](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/cluster-to-advanced-cluster-migration-guide). |
There was a problem hiding this comment.
Adjusted deprecation message to make it stand out more. Also noticed message below was outdated as it had a softer recommendation, removed as all details can now be found in the dedicated migration guide.
|
APIx bot: a message has been sent to Docs Slack channel |
There was a problem hiding this comment.
Pull Request Overview
This PR reorganizes the MongoDB Atlas Terraform provider documentation by adding subcategory frontmatter to all documentation pages and standardizing deprecation notice formatting. The primary goal is to improve documentation organization in the Terraform Registry by grouping resources and data sources by feature.
Key changes:
- Added YAML frontmatter with subcategory metadata to 200+ documentation files
- Standardized deprecation notice formatting from "WARNING:" to "~> DEPRECATION:"
- Moved deprecated resources from "Deprecated" subcategory to their appropriate feature subcategories
Reviewed Changes
Copilot reviewed 219 out of 219 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| templates/resources/*.md.tmpl | Added subcategory frontmatter to resource documentation templates |
| templates/data-sources/*.md.tmpl | Added subcategory frontmatter to data source documentation templates |
| docs/resources/*.md | Added subcategory frontmatter to resource documentation files |
| docs/data-sources/*.md | Added subcategory frontmatter to data source documentation files |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
There was a problem hiding this comment.
Feels like a bit too many categories IMO.
Suggestions:
- Remove extra flex categories: Flex Restore Jobs/ Flex Snapshots --> use Flex Clusters instead
- Is shared tier really necessary? Looks like we only have datasources
- Missing a bigger project category with auditing and maintenance window and possibly more
- Organization could also be a bigger category
- Network could be a separte category.
Curious to the reasoning behind these categories?
| @@ -1,3 +1,7 @@ | |||
| --- | |||
| subcategory: "Event Trigger" | |||
There was a problem hiding this comment.
should be in "Realm API" category according to PD appendix, same for other trigger docs
There was a problem hiding this comment.
There is an explicit note in the PD Two exceptions to the resource group matching will be needed at launch: roles_org_id will not go under Root but Organization and event_trigger will simply go under Event Trigger..
Do we have context of who created the appendix section? It seems to be inconsistent. cc @maastha in case you have more context.
Description
Link to any related issue(s): CLOUDP-334500
Changes include:
Note: For reviewing highly suggest looking into https://registry.terraform.io/providers/AgustinBettati/agustinbettati/0.0.6/docs which shows how the resulting docs will look.
Type of change:
Required Checklist:
Further comments