RDBTC-221 Migrate technical guides Migrating RDBTC-88

[Netzach-Nyss]

Issue link

RDBTC-88 How to connect RavenDB 7.0 logs to Grafana Cloud
RDBTC-221 Migrate technical guides and how-tos from ravend.net/articles to docs.ravendb.net/guides

Additional description

Content Quality & E-E-A-T Analysis (re-run)

Content Quality Score: 79/100 _{(was 72)}

E-E-A-T Breakdown

Factor	Score	Key Signals
Experience	22/25 (=)	4 original annotated screenshots; first-person walkthrough; the read-only-token gotcha. No new first-hand evidence added this round
Expertise	22/25 (+1)	The rewritten Summary and objectives now articulate the mechanism (two settings.json entries, target runs alongside the file target, levels= as the dial) rather than just the steps. Still no label-cardinality caveat
Authoritativeness	18/25 (+1)	Legacy article-page URL replaced with a build-checked internal link. Still only 1 internal link, and the canonical config still lives in a personal gist
Trustworthiness	20/25 (=)	Byline, dates, HTTPS, TechArticle schema intact. Version pin and content age untouched

E-E-A-T subtotal: 82/100 _{(was 80)}

Metrics

Metric	Before	Now	Assessment
Body words	1,317	1,497	Clears the 1,500 floor in spirit; coverage still the real gap
Flesch Reading Ease	61.2	62.5	On target
Grade level	8.9	8.9	Good for developers
Avg sentence length	16.7	17.7	On target
Descriptive headings	7/12	12/12	Fixed
Internal links (inline)	0	1	Still short of 4–6 at this length
Markup artifacts	144 smart chars + escapes	0	Fixed
Keyword density	grafana 3.12%	grafana 2.87%	Improved into the natural band
Images with alt text	4/4	4/4	Unchanged

AI Citation Readiness: 72/100 _{(was 55)}

The step headings and the Summary were the two biggest losses last run, and both are now resolved. ### Step 3: Add the Loki target is retrievable on its own; the Summary's four bullets are genuinely quotable statements about how the integration works. Wrapping the config tokens in inline code also gives extractors clean boundaries around Logs.ConfigPath, writeTo="loki", and levels=.

Remaining losses: no reference table for the five placeholder values, no troubleshooting Q&A, TechArticle rather than HowTo schema on what is a five-step procedure, and conversational lead-ins before each instruction (deliberate house tone, so this is a real ceiling rather than a defect).

Issues Found

Correction to my previous report. I said this page had 2 inbound guide links and was "not orphaned." That was wrong on both counts. Re-checking across guides/, docs/, src/ and the other content dirs returns exactly two references, and neither is an internal link:

• how-is-my-database-today.mdx:247 links to https://ravendb.net/articles/sending-your-ravendb-7-0-logs-to-grafana-cloud
• overview.mdx:445 links to the same external URL

My earlier grep also reported a match in the Datadog guide; that file contains no reference to this guide at all. So the page has zero internal inbound links, and two places that should point at it are sending users and crawlers to the external ravendb.net article instead. That external article is a near-duplicate of this page competing for the same query, which is a cannibalization risk worth checking. It also violates the house convention that guide cross-links use ./slug, never ravendb.net/articles/....

Still open from the previous run (not in the fix scope you gave me)

1. Freshness / version drift — still the top-ranked issue. Title, description and intro pin to RavenDB 7.0 against current 7.2; NLog.Targets.Loki pinned to 2.2.0; 4 Grafana Cloud screenshots from Feb 2025.
2. Internal linking — 1 link across 1,291 prose words. logs-configuration.mdx, monitoring/logging/configuration.mdx and monitoring/logging/overview.mdx all exist and are still unlinked from the body.
3. No verification or troubleshooting section.
4. Canonical config is a personal gist.
5. No image frontmatter → no per-page OG preview. (icon: "grafana" does resolve to grafana.svg, so the guide card renders correctly.)
6. Site-level: every authors.json entry has no url, so the emitted Person schema carries no url/sameAs.

New / minor

13. One Summary bullet runs 32 words ("Once the server restarts, the levels= attribute..."). Splitting it would improve its standalone quotability. My wording, my fix to make if you want it.

Recommendations (ranked)

1. Fix the two external self-references in how-is-my-database-today.mdx:247 and overview.mdx:445 to point at /guides/sending-your-ravendb-7-0-logs-to-grafana-cloud. This is cheap, it is the page's only inbound-link source, and it stops the docs from promoting a competing external duplicate. New top priority.
2. Refresh for 7.2 (title, package version, screenshots), then commit so git dateModified reflects it.
3. Add 3–5 more inline internal links to the logging-config docs and sibling observability guides.
4. Convert the five placeholder values into a reference table (Setting · Where to find it in Grafana · Example).
5. Add a ## Troubleshooting section covering the known failure modes.
6. Inline the full config instead of depending on the gist.

The six issues you assigned are all verified fixed: zero smart quotes or escape artifacts, zero legacy article-page URLs, all five step headings descriptive, Summary rewritten as four plain-text takeaways, objectives expanded to five bullets, administration tag added. The file compiles clean through @mdx-js/mdx.

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)