RDBTC-221 Migrate technical guides Migrating RDBTC-85

[Netzach-Nyss]

Issue link

RDBTC-85 How to troubleshoot high CPU usage
RDBTC-221 Migrate technical guides and how-tos from ravend.net/articles to docs.ravendb.net/guides

Additional description

Content Quality Score: 82/100

(previous pass: 68/100)

Verified against the rendered build output at build/guides/how-to-troubleshoot-ravendbs-high-cpu-usage/index.html, not just the source.

Measured metrics

Metric	Before	Now	Assessment
Prose words	1,311	1,638	Above the 1,500 blog floor
Flesch Reading Ease	66.1	65.9	In the 60-70 band
Grade level	7.7	7.9	Appropriate
Avg sentence length	14.7w	15.3w	In the 15-20 target
Avg paragraph	41w	45.5w	Slightly long, still scannable
Headings (H2/H3/H4)	6/6/3	6/9/3	Clean hierarchy, no skips
Inline internal links	0	9 (5.5/1k)	Top of the 3-5/1k band
External links	2	5	Reasonable
Images with alt	11/11	11/11 (avg 9.2 words)	Strong
Code blocks tagged	0/5	5/5	Fixed
Broken links	1	0	Build-verified
"troubleshoot" in body	0	0	Title/H1 term still absent from prose

Keyword profile is healthy: cpu 2.69%, current cpu usage 1.10%, total cpu time 0.92%, high cpu usage 0.92%. All within the 1-3% natural band with no stuffing. cpu, ravendb, and high cpu usage all appear in the first 100 words.

---

E-E-A-T Breakdown

Factor	Score	Key Signals
Experience	20/25 (+1)	11 original screenshots from the author's own machine; first-person demonstration retained. The expanded causes now carry practitioner heuristics ("if your spikes land on a schedule rather than following your traffic"). Still zero real incident data, no CPU numbers, no thresholds anywhere
Expertise	20/25 (+4)	Causes went 3 → 6, each with a diagnostic tell. Nine links into primary RavenDB docs show depth. Terminology now consistent. Held back by the Windows dead end and the total absence of concrete figures
Authoritativeness	21/25 (+4)	Vendor's own docs domain. Verified entity graph in the rendered head: five JSON-LD blocks (TechArticle, BreadcrumbList, WebSite, Organization, SoftwareApplication). Author entity carries jobTitle: Technical Writer and worksFor: RavenDB. Only 2 external citations
Trustworthiness	22/25 (+3)	Broken see_also fixed, truncated sentence and malformed table gone. Verified visible byline in rendered HTML: "Paweł Lachowski, Technical Writer, Published on February 23, 2025". Canonical correct, no stray noindex. Loses points for no visible update date

Total: 83/100 (was 71/100)

AI Citation Readiness: 72/100

(previous pass: 58/100)

Gained: a parseable comparison table, consistent entity naming, parallel definition patterns ("Current CPU Usage (In RavenDB called Current CPU %)" / "Total CPU Time (in RavenDB called Overall CPU Time)"), and a verified five-block entity graph.

Still capped by: no Q&A blocks, an intro that answers nothing, zero statistics, and one section (Windows) that poses a question and declines to answer it.

---

Issues Found

New this pass

1. Guide tags never reach schema keywords. The rendered TechArticle has keywords: None despite frontmatter tags: [perf-tuning, troubleshooting, deep-dive]. Cause: index.tsx:139 passes keywords={frontMatter.keywords}, but guides declare tags:, not keywords:. Only 3 of 77 guides define a keywords field, so this path is effectively dead site-wide. Samples handle it correctly by mapping their three tag arrays into keywords. This is a one-line fix in the theme component that would populate keywords across all 77 guides, not just this one.

2. No visible "last updated" date. Schema carries dateModified: 2026-05-22 against datePublished: 2025-02-23, but the rendered page shows only "Published on February 23, 2025". Readers and quality raters see an 18-month-old date with no revision marker, on a topic whose screenshots are version-sensitive. The signal is already earned in schema; it just isn't surfaced.

3. proficiency_level: Expert is in schema but not rendered. Minor, but it is a relevance cue that costs nothing to display.

4. Inline link density is 5.5 per 1,000 words, just above the 3-5 guideline. Not a defect, and all nine are contextually relevant. Flagging only so no more get added.

Carried over (the items deferred by scope)

5. Windows section is still a dead end. Unchanged, and now the single clearest weakness. It remains the only place where the guide raises a question and supplies no answer, which costs on both Expertise and AI citation.

6. No FAQ section. The largest remaining GEO lever.

7. Intro is not answer-first, and still opens with a sentence fragment ("Whether you noticed it on the RavenDB dashboard or started investigating why your tasks take so long to finish.").

8. Zero statistics or first-party data. No CPU percentages, no "normal looks like X" baseline, no timings. First-party data is among the most-cited content types by AI systems, and this guide has none.

9. "troubleshoot" appears 0 times in the body despite being in the title, slug, and H1.

10. No image: frontmatter. Confirmed low impact: og:image is a fixed site-wide card regardless, so this only affects FeaturedGuides placement.

---

Recommendations

Ranked by impact per effort:

1. Fix the Windows section. Biggest single quality gain remaining, and the only item that is a genuine correctness gap rather than an enhancement.
2. Add an FAQ section. Biggest citation gain. Six guides already have one, across three heading styles, so pick a form while you're there.
3. Fix the keywords mapping in the theme component. Cheapest fix on the list, and it improves all 77 guides at once rather than this one.
4. Surface the last-updated date on guide pages. The data already exists in schema; it just needs rendering.
5. Add one or two concrete numbers to the guide, even something as simple as what a healthy idle Current CPU % looks like. This is the missing first-party-data signal and it would lift Experience, Expertise, and citation readiness together.
6. Work "troubleshoot" into the opening prose naturally, most easily as part of an answer-first rewrite of the intro, which handles issues 7 and 9 in one edit.

Items 1, 2, and 5 are the substantive ones. Items 3, 4, 6 are mechanical.

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)