Fix non-functional sample code and remove orphaned stub pages

[GuanzhouSong]

Six reviews (Opus 5, Opus 4.8, GPT-5.6 Sol — two repos each) scored the docs against a written standard derived from Diátaxis, the CloudNativePG layout, the PostgreSQL documentation guide, and failures reproduced against DocumentDB's own published pages.

Docs-repo mean: 20.7/50. All three reviewers described the same shape: a strong reference core (postgres-api/, api-reference/, documentdb-local/, kubernetes-operator/) attached to a decaying getting-started front door — which is where a new user lands.

One reviewer executed the samples against a live gateway instead of reading them. python-setup.md failed six different ways.

---

1. python-setup.md was not runnable

Line	Failure
108	datetime.utcnow() used 43 lines before its import → NameError on copy-paste
162	initialize_ordered_bulk_op() — removed in PyMongo 4.0
187	$vectorSearch passed to find() → unknown top level operator: $vectorSearch. It is an aggregation stage and must be first in the pipeline
201	from documentdb_api import DocumentDB — no such package, not on PyPI, not in this project
219	pymongo.errors.ConnectionError doesn't exist → AttributeError inside the error-handling example
250	try: whose body is only a comment → IndentationError

The documentdb_api block is deleted rather than repaired — there is nothing real to point it at.

2. The vector index could not be created as documented

createIndex rejects the cosmosSearchOptions spec:

Index type 'CosmosSearch' was requested, but the 'cosmosSearch' options were not provided.

Switched to the createIndexes runCommand form, which works, and the error string is now named so anyone who already hit it can find this page.

3. A security claim that was backwards

vscode-quickstart.md said: "You must set these when creating the container for authentication to work."

False, and it inverts a real risk. Omitting --username/--password starts the container with the built-in default_user / Admin100 — public credentials that authenticate. Verified live. The page now says so.

4. Stale prerequisites that fail confusingly

Node.js 14.x or later against a driver requiring >=20.19; Python 3.7+ against PyMongo requiring >=3.9.

5. 54 lines of empty catalogue

nodejs-setup.md had seven headings whose bodies were numbered topic lists with no content — promising bulk operations, transactions, testing and deployment guidance that does not exist. Replaced with a working CRUD example and one honest pointer.

6. Deletions

vscode-extension-guide.md — 268 lines the website already replaces with a redirect to the Quick Start, carrying a hardcoded password123, a docker image rm that deletes the image it just told you to run, and "created_at": new Date(2024-11-16) — invalid JSON, and as JavaScript it evaluates 2024-11-16 to 1997, yielding a 1970 date. Collapsed to a pointer.

Five orphan stubs — aws-setup, azure-setup, gcp-setup, yugabyte-setup, mongodb-migration. Verified 0 references: absent from navigation.yml, unlinked from every page, yet live indexable URLs. Each is a title plus a restated description with no procedure — gcp-setup is one sentence; azure-setup ends on a bare ## Setup heading with nothing under it. A 15-word page ranking for a real query is worse than a 404.

Removing azure-setup also retires the Micrtosoft typo that the website was patching at runtime (articleService.ts carried a .replace(/Micrtosoft/g, 'Microsoft')) — a band-aid over a source typo, now unnecessary.

---

Note on the review process

Two of six reviewers reported a "broken URI" containing ****** in this repo. That was the credential-redaction filter masking mongodb://user:pass@host in their own transcripts — ****** appears nowhere in the repo. Verified against raw bytes and discarded; one reviewer caught it independently. Nothing here was changed without confirming it in the actual file.

Related

documentdb/documentdb.github.io#161 — the website half: broken certificate path, the false sample-data default, an ARM-breaking mongosh repo URL, and the missing Docker lifecycle.

[guanzhousongmicrosoft]

Sample code failures reproduced; orphan stubs confirmed unreferenced. Approving.