RDBTC-221 Migrate technical guides Migrating RDBTC-160

[Netzach-Nyss]

Issue link

RDBTC-221 Migrate technical guides and how-tos from ravend.net/articles to docs.ravendb.net/guides
RDBTC-160 Practical Look at AI Agents

Additional description

Content Quality & E-E-A-T Analysis

Content Quality Score: 90/100

Metrics

Metric	Value	Change	Assessment
Prose words	2,751	+1	Well past the floor
Sentences	132, avg 20.9 words	—	Marginally over the band
Flesch RE / FK Grade	55.7 / 10.7	-0.2	Fine for Expert audience
Paragraphs	81, avg 2.0 sentences	—	In band
Headings	6x H2, 4x H3, no skips	—	Correct
Internal links out	11 (4.0 per 1000 words)	—	On target
Internal links in	8, all internal	+6 converted	Properly clustered
External links	3, descriptive anchors	—	Good
Images	21, all with alt	—	Excellent
FAQ pairs	6	—	Strong
Citable numbers in prose	32768, 1024	+2	First concrete figures
Tables	0	—	Still a gap
Keyword density ("agent")	2.65%	—	In band

The page now links out to 11 docs pages and receives 8 internal links, none of which leak to an external duplicate. That bidirectional clustering is the main structural change since the last pass.

E-E-A-T Breakdown

Factor	Score	Change	Key Signals
Experience	22/25	—	Unchanged. 21 original screenshots, failures left visible, the malicious-prompt test. The two new numbers are product defaults, not measured results, so they do not move this.
Expertise	23/25	—	FAQ depth beyond the walkthrough: SendToModel = false, the @conversation collection, MaxModelIterationsPerCall. All cited to primary docs.
Authoritativeness	22/25	+2	All six inbound links that previously pointed at the ravendb.net duplicate now resolve to this page, verified in built HTML across both 7.2 and 7.1. Still capped because the duplicate itself is live and competing.
Trustworthiness	23/25	+2	The MaxTokensAfterSummarization contradiction is gone, resolved against three independent sources including the guide's own screenshot. That removed the page's only factual inconsistency, which is a named low-quality marker in the Sept 2025 QRG.

Total: 90/100

AI Citation Readiness: 80/100

Signal	Status
Question-answer format	Strong, 6 pairs
Heading hierarchy	Strong
Quotable summary	Strong
Source attribution	Strong, 11 citations
Extractable figures	Improved, 2 present
Comparative tables	Absent
First-party data	Absent
FAQ structured data	Absent

---

Issues Found

1. Stale version claim (high, open since pass one)

Line 80 still reads "In the latest RavenDB update (7.1.2)". Current is 7.2. This is now the only content-accuracy defect left on the page, and it has survived four passes. The prerequisites block at line 134 correctly states "RavenDB 7.1.2 or later" as a floor and needs no change.

2. The duplicate is still live and uncanonicalized (high, external)

Re-fetched today: ravendb.net/articles/practical-look-at-ai-agents-with-ravendb returns 200 with the full article, no canonical, no noindex.

3. Systemic version of the same problem, untouched (high)

23 other articles have a local guide with an identical slug while 61 links across the repo still point at the external copy. The heaviest are setting-up-ravendb-cluster-on-aws-eks (9), ravendb-deployment-guide-docker-compose-cluster (9), survive-the-ai-tidal-wave-with-ravendb-genai (5), and sending-your-ravendb-7-0-logs-to-grafana-cloud (5). I have not touched these, since the retention decision differs per article.

4. No FAQPage schema (medium)

Six question-answer pairs, no structured data for them. DocPageMetadata.tsx emits TechArticle and SoftwareSourceCode only. Site-wide: 15 pages carry FAQ content, 3 of them in a directly parseable bold-question format. Value is AI parsing on ChatGPT, Perplexity, and Bing Copilot, not SERP rich results, which Google retired for most sites in 2023.

5. Author entity still thin (medium)

"url": null, "socials": {}. Person schema emits no url and no sameAs.

6. No first-party data (medium)

Now the single largest remaining AI-citation gap. The two figures added are documented defaults. Nothing on the page reports a measurement the author actually took.

7. No comparison table (medium) and 8. sentence-length drift (low, mine), both unchanged from the last pass.

---

Recommendations

Fix line 80. One sentence, open for four passes, and it is the last factual defect. Reframe 7.1.2 as the release that introduced the feature rather than as the current one.

Decide the fate of the ravendb.net copy, then either canonical it here or retire it. Everything done on this page so far improves a copy that still competes with an uncanonicalized twin.

Batch the remaining 61 links. I can repoint all of them in one pass, or produce the 23-article list as a checklist so the retention call gets made per article first. Say which.

Add FAQPage schema behind an optional frontmatter flag, scoped as its own task rather than folded into this page.

Add the Query vs Action table, which now has a natural home beside the FAQ.

Populate the author entry. One line, lifts every guide by this author.

Add one measured number. Unchanged across four passes and still the highest-value single addition available.

---

Type of change

• Content - docs
• Content - cloud
• Content - Quill
• Content - guides
• Content - start pages/other
• New docs feature (consider updating /templates or readme)
• Bug fix
• Optimization
• Other

Changes in docs URLs

• No changes in docs URLs
• Articles are restructured, URLs will change, mapping is required (update /scripts/redirects.json file, set Documents Moved PR label)

Changes in UX/UI

• No changes in UX/UI
• Changes in UX/UI (include screenshots and description)