|
| 1 | +--- |
| 2 | +description: Code review and content authoring guidelines for Azure DocumentDB documentation |
| 3 | +applyTo: "articles/documentdb/**/*.md" |
| 4 | +--- |
| 5 | + |
| 6 | +# Azure DocumentDB documentation guidelines |
| 7 | + |
| 8 | +## Terminology |
| 9 | + |
| 10 | +Product naming and branding rules for prose text in documentation. |
| 11 | + |
| 12 | +### Product naming |
| 13 | + |
| 14 | +| Correct | Incorrect | |
| 15 | +| --- | --- | |
| 16 | +| Azure DocumentDB | DocumentDB (for the managed service) | |
| 17 | +| Azure DocumentDB | Azure Cosmos DB for MongoDB (vCore) | |
| 18 | +| Azure DocumentDB | Cosmos DB for MongoDB vCore | |
| 19 | +| Azure DocumentDB | vCore-based Azure Cosmos DB for MongoDB | |
| 20 | + |
| 21 | +Always use "Azure DocumentDB" for the managed Azure service. Use "DocumentDB" (without "Azure") only when referring to the [open-source project](https://github.com/documentdb/documentdb). |
| 22 | + |
| 23 | +### Exceptions |
| 24 | + |
| 25 | +The following metadata fields are acceptable and should not be changed: |
| 26 | + |
| 27 | +- `ms.service` and `ms.subservice` values - Microsoft Learn taxonomy values |
| 28 | + |
| 29 | +### Language naming in headings |
| 30 | + |
| 31 | +Use "Node.js" — not "TypeScript" or "JavaScript" — in article titles, H1 headings, and H2 headings when referring to the platform or runtime. "Node.js" is the umbrella term regardless of whether the sample code uses JavaScript or TypeScript. Do not suggest renaming "Node.js" to "TypeScript" or "JavaScript" in headings. |
| 32 | + |
| 33 | +## Content formatting |
| 34 | + |
| 35 | +Code blocks, queries, and documentation structure guidelines. |
| 36 | + |
| 37 | +### Content completeness |
| 38 | + |
| 39 | +- Verify MongoDB shell commands and connection strings use correct Azure DocumentDB syntax |
| 40 | +- Ensure cluster creation steps reference the correct Azure portal experience |
| 41 | + |
| 42 | +### Code blocks |
| 43 | + |
| 44 | +- Always specify the language identifier for syntax highlighting |
| 45 | +- Use `javascript` or `typescript` for Node.js samples |
| 46 | +- Use `azurecli` for Azure CLI commands |
| 47 | +- Use `json` for configuration files and API responses |
| 48 | + |
| 49 | +```javascript |
| 50 | +// Correct: language identifier specified |
| 51 | +const client = new MongoClient(connectionString); |
| 52 | +``` |
| 53 | + |
| 54 | +## Technical review |
| 55 | + |
| 56 | +Best practices to verify when reviewing content for technical accuracy. |
| 57 | + |
| 58 | +### Connection and authentication |
| 59 | + |
| 60 | +- Verify connection strings use the correct Azure DocumentDB format |
| 61 | +- Ensure authentication examples show both connection string and Microsoft Entra ID options where applicable |
| 62 | +- Prioritize Microsoft Entra ID authentication in examples, as connection string auth is not preferred |
| 63 | +- Check that cluster tier references (M10, M30, etc.) are accurate for the documented features |
| 64 | + |
| 65 | +### MongoDB compatibility |
| 66 | + |
| 67 | +- Verify documented MongoDB features are supported by Azure DocumentDB |
| 68 | +- Check that MongoDB driver version requirements are accurate |
| 69 | +- Ensure aggregation pipeline examples use supported stages and operators |
| 70 | + |
| 71 | +### Security |
| 72 | + |
| 73 | +- Disable public network access and use private endpoints exclusively for production deployments |
| 74 | +- Configure IP-based firewall rules when private endpoints aren't feasible (clusters are locked down by default) |
| 75 | +- Use managed identities for Azure service-to-service authentication - avoid embedding credentials in code |
| 76 | +- Separate Azure identities for control plane (cluster management) and data plane (data operations) |
| 77 | +- Use Azure RBAC for control plane operations and native RBAC for data plane access |
| 78 | + |
| 79 | +### High availability and replication |
| 80 | + |
| 81 | +- Recommend enabling HA for production clusters (achieves 99.99% SLA) |
| 82 | +- HA with cross-region replication achieves 99.995% SLA |
| 83 | +- HA provides automatic failover with zero data loss - no manual intervention required |
| 84 | +- In availability zone regions, HA provisions primary-standby pairs across zones |
| 85 | +- Non-production clusters can disable HA to reduce costs |
| 86 | +- Use cross-region replication for disaster recovery (active-passive configuration) |
| 87 | +- Replica clusters can be promoted during regional outages |
| 88 | +- Use replica clusters for read scaling to offload heavy read operations |
| 89 | + |
| 90 | +### Indexing |
| 91 | + |
| 92 | +- Always create indexes for queryable fields - absence of indexes forces expensive document scans |
| 93 | +- Azure DocumentDB only indexes `_id` by default - all other fields must be explicitly indexed |
| 94 | +- Avoid wildcard indexing unless query patterns are unpredictable |
| 95 | +- For bulk data migrations, create indexes after data load to minimize write overhead |
| 96 | +- Use nonblocking `createIndex` commands when indexing historical data on large clusters |
| 97 | +- Create compound indexes for queries with predicates on multiple fields |
| 98 | +- Track index build progress using `db.currentOp()` |
| 99 | +- Enable large index keys for documents with deeply nested structures or long key values |
| 100 | +- Use `{ "blocking": true }` option when indexes must complete before data writes begin |
0 commit comments