docs: SEO & AEO optimization across 23 core pages#1074
Conversation
- Rewrite FAQ pages with H2 question headings (replacing Accordion-only format) and inject FAQPage JSON-LD structured data for Google Rich Snippets - Optimize title and meta description frontmatter across 20+ high-traffic pages with target keywords (streaming database, PostgreSQL-compatible, real-time, etc.) - Add descriptive alt attributes to images for accessibility and image SEO - Rewrite opening paragraphs to be self-contained answers for AEO (Answer Engine Optimization) — enabling AI search engines to cite directly - Improve internal cross-linking with descriptive anchor text - Convert nested Accordion content to structured Markdown with tables and headers Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR updates core RisingWave docs pages to improve SEO/AEO by rewriting titles/meta descriptions and opening paragraphs, adding missing image alt text, and restructuring FAQ pages with H2 question headings plus FAQPage JSON‑LD.
Changes:
- Rewrites/optimizes frontmatter (
title,description,sidebarTitle) across 20+ pages for search intent and richer snippets. - Refactors FAQ pages from Accordion-only layouts to H2-based Q&A and injects
FAQPageJSON-LD. - Adds/expands first-paragraph “direct answer” content and improves accessibility via image
alttext.
Reviewed changes
Copilot reviewed 23 out of 23 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| store/overview.mdx | Updates title/description and reframes storage intro around Hummock + Iceberg. |
| sql/overview.mdx | Updates SEO-focused title/description and frontmatter layout key. |
| sql/commands/sql-create-mv.mdx | Updates title/description and adds sidebarTitle for the CREATE MV reference page. |
| serve/overview.mdx | Updates “Access” page title/description for query/serving keywords. |
| reference/risingwave-flink-comparison.mdx | Updates comparison page title/description for search-friendly phrasing. |
| reference/key-concepts.mdx | Renames “Glossary” page and adds a clarifying intro paragraph. |
| processing/overview.mdx | Rewrites overview and strengthens positioning around SQL-based streaming + ad-hoc queries. |
| ingestion/sources/postgresql/pg-cdc.mdx | Updates title/description to emphasize native Postgres CDC replication. |
| ingestion/sources/mysql/mysql-cdc.mdx | Updates title/description to emphasize native MySQL CDC replication. |
| ingestion/sources/kafka.mdx | Updates title/description to better match Kafka connector search terms. |
| ingestion/overview.mdx | Updates title/description around ingestion patterns (stream/batch/CDC). |
| ingestion/cdc-with-risingwave.mdx | Updates title/description and rewrites intro for CDC landing page. |
| iceberg/overview.mdx | Updates title/description for Iceberg integration positioning. |
| get-started/use-cases.mdx | Rewrites page intro to be a self-contained “answer-first” overview. |
| get-started/source-table-mv-sink.mdx | Updates title/description for core object concepts and keywords. |
| get-started/quickstart.mdx | Updates title/description to be more task/outcome oriented. |
| get-started/intro.mdx | Updates title/description, adds an answer-first intro paragraph, and adds image alt text. |
| get-started/architecture.mdx | Updates title/description, rewrites intro paragraph, and adds image alt text. |
| faq/faq-when-to-use-risingwave.mdx | Converts to H2 Q&A format, adds alt text, and injects FAQ JSON-LD. |
| faq/faq-using-risingwave.mdx | Converts to H2 Q&A format and injects FAQ JSON-LD. |
| faq/faq-overview.mdx | Updates title/description and improves card copy/order. |
| deploy/deployment-modes-overview.mdx | Updates title/description and adds sidebarTitle. |
| delivery/overview.mdx | Updates title/description to emphasize sinks/delivery keywords. |
faq/faq-when-to-use-risingwave.mdx
Outdated
| - **Streaming state management**: Storing operators' internal state such as hash tables, aggregation buffers, and join state efficiently. | ||
| - **Point queries**: Ad-hoc queries on stored data that look up specific rows by key, which is a common access pattern for serving workloads. | ||
|
|
||
| For analytical queries that benefit from columnar storage, RisingWave supports native [Apache Iceberg table engine](/iceberg/iceberg-table-engine), allowing you to store and query data in columnar format alongside row-based storage. |
There was a problem hiding this comment.
The link target /iceberg/iceberg-table-engine does not exist in this repo (no corresponding .mdx), so this will render as a dead link. Consider pointing to an existing Iceberg engine page such as /iceberg/internal-iceberg-tables or the general /iceberg/overview page.
| For analytical queries that benefit from columnar storage, RisingWave supports native [Apache Iceberg table engine](/iceberg/iceberg-table-engine), allowing you to store and query data in columnar format alongside row-based storage. | |
| For analytical queries that benefit from columnar storage, RisingWave supports native [Apache Iceberg table engine](/iceberg/internal-iceberg-tables), allowing you to store and query data in columnar format alongside row-based storage. |
store/overview.mdx
Outdated
| title: "RisingWave storage | Hummock row store & Apache Iceberg columnar engine" | ||
| sidebarTitle: "Storage" | ||
| description: Learn how RisingWave stores data (Hummock and Iceberg) and where persisted data lives. | ||
| description: "Understand how RisingWave stores data: Hummock row-based storage on object storage (S3, GCS) for streaming state, and native Apache Iceberg columnar engine for analytics. Two storage options compared." | ||
| --- | ||
|
|
||
| This page explains **what it means to “store data” in RisingWave**, where the persisted data lives, and how to choose between RisingWave’s two storage options. | ||
| RisingWave offers two storage engines: **Hummock**, a row-based LSM-tree engine that stores tables, materialized views, and streaming state in object storage (S3, GCS, Azure Blob), and a native **Apache Iceberg columnar engine** for analytics workloads. This page explains what data gets persisted, where it lives, and how to choose between the two options. |
There was a problem hiding this comment.
The page describes Iceberg as a “columnar engine” and says RisingWave has “two storage engines”. In the rest of the docs Iceberg is referred to as the “Iceberg table engine” / Iceberg table format rather than a storage engine on its own. Consider adjusting the terminology here to match the existing Iceberg docs to avoid confusing readers about what is actually a RisingWave storage engine vs an Iceberg-backed table option.
get-started/intro.mdx
Outdated
| --- | ||
| import { Button } from '/snippets/button.mdx'; | ||
|
|
||
| RisingWave is an open-source streaming database that is wire-compatible with PostgreSQL. It provides a unified platform for real-time data ingestion from 20+ sources (Kafka, CDC, S3), stream processing via incrementally maintained materialized views, low-latency serving with sub-20ms p99 query latency, and native Apache Iceberg lakehouse management. RisingWave stores data in object storage (S3, GCS, Azure Blob) for cost efficiency and infinite scalability, and can be deployed via Docker, Kubernetes, or the fully managed RisingWave Cloud. |
There was a problem hiding this comment.
The intro paragraph includes a specific performance claim (“sub-20ms p99 query latency”) without any benchmark link, methodology, or environment details. This kind of hard number tends to become inaccurate quickly and can be misleading in docs; consider removing the numeric claim or linking to a maintained benchmark page and stating the conditions under which it was measured.
| RisingWave is an open-source streaming database that is wire-compatible with PostgreSQL. It provides a unified platform for real-time data ingestion from 20+ sources (Kafka, CDC, S3), stream processing via incrementally maintained materialized views, low-latency serving with sub-20ms p99 query latency, and native Apache Iceberg lakehouse management. RisingWave stores data in object storage (S3, GCS, Azure Blob) for cost efficiency and infinite scalability, and can be deployed via Docker, Kubernetes, or the fully managed RisingWave Cloud. | |
| RisingWave is an open-source streaming database that is wire-compatible with PostgreSQL. It provides a unified platform for real-time data ingestion from 20+ sources (Kafka, CDC, S3), stream processing via incrementally maintained materialized views, low-latency serving, and native Apache Iceberg lakehouse management. RisingWave stores data in object storage (S3, GCS, Azure Blob) for cost efficiency and infinite scalability, and can be deployed via Docker, Kubernetes, or the fully managed RisingWave Cloud. |
processing/overview.mdx
Outdated
| **Easy to use**: By aligning with PostgreSQL's syntax, functions, and data types, RisingWave minimizes the learning curve. Even for creating streaming jobs, there is no need to learn streaming-specific concepts — just write standard SQL. | ||
|
|
||
| **Powerful**: RisingWave fully supports and optimizes a variety of SQL features, including advanced features such OVER window and different kinds of JOINs. At the same time, we are also committed to expanding the expressive power of SQL, such as by adding semi-structured data types and corresponding expressions. | ||
| **Powerful**: RisingWave fully supports advanced SQL features including OVER window functions, multi-way JOINs (inner, outer, semi, anti), time-windowed aggregations (tumble, hop, session), and semi-structured data types (JSONB, arrays, structs). |
There was a problem hiding this comment.
This line lists “semi” and “anti” as JOIN types. Elsewhere the SQL docs describe joined tables as supporting inner/outer/cross joins (see sql/query-syntax/from-clause.mdx), so this phrasing is inconsistent and may imply unsupported syntax. Consider aligning the wording with the documented join types or clarifying how semi/anti semantics are expressed (e.g., via EXISTS/NOT EXISTS) if that’s what’s intended.
| **Powerful**: RisingWave fully supports advanced SQL features including OVER window functions, multi-way JOINs (inner, outer, semi, anti), time-windowed aggregations (tumble, hop, session), and semi-structured data types (JSONB, arrays, structs). | |
| **Powerful**: RisingWave fully supports advanced SQL features including OVER window functions, multi-way JOINs (inner, outer, cross) and semi/anti join semantics (for example, using `EXISTS` / `NOT EXISTS`), time-windowed aggregations (tumble, hop, session), and semi-structured data types (JSONB, arrays, structs). |
yingjunwu
left a comment
yingjunwu
left a comment
There was a problem hiding this comment.
Tech Writer Review: SEO & AEO optimization
Overall this is a solid SEO/AEO optimization pass. The FAQ restructuring from Accordions to H2 headings is the biggest win, and the JSON-LD structured data is a nice addition. A few items to address:
🔴 Issues to Fix
1. Many titles exceed Google's ~60 character display limit
These will get truncated in SERPs, which hurts CTR — the opposite of what we want:
| Page | Title | Length |
|---|---|---|
deploy/deployment-modes-overview |
"Deploy RisingWave | Docker, Kubernetes, Helm & Cloud deployment options" | 73 |
get-started/use-cases |
"RisingWave use cases | Streaming analytics, fraud detection & real-time ETL" | 77 |
ingestion/cdc-with-risingwave |
"Change data capture (CDC) with RisingWave | Real-time database replication" | 75 |
ingestion/overview |
"Data ingestion patterns | Stream, batch & CDC ingestion into RisingWave" | 72 |
reference/risingwave-flink-comparison |
"RisingWave vs. Apache Flink | Feature comparison for stream processing" | 72 |
store/overview |
"RisingWave storage | Hummock row store & Apache Iceberg columnar engine" | 72 |
processing/overview |
"Real-time data processing in RisingWave | Streaming & ad-hoc queries" | 70 |
get-started/architecture |
"RisingWave architecture | Serving, streaming, meta & compactor nodes" | 70 |
serve/overview |
"Query & serve data from RisingWave | SQL, FDW & visualization tools" | 68 |
Recommend trimming to ≤60 chars. The part after | is the one Google tends to cut — so front-load the valuable keywords.
2. Some meta descriptions exceed ~160 characters and will get truncated
Examples:
faq/faq-overview: 214 charsdeploy/deployment-modes-overview: 186 charsdelivery/overview: 177 chars
Trim to ~150-155 chars. Put the most important keywords/info in the first 150 chars.
3. JSON-LD rendering in Mintlify needs verification
The {JSON.stringify({...})} pattern inside <script type="application/ld+json"> is a JSX/MDX approach. Need to confirm Mintlify actually executes this at build time and outputs valid JSON-LD in the HTML. If Mintlify doesn't process JSX expressions inside <script> tags, the structured data will be broken. Suggest testing with a deploy preview and validating with the Rich Results Test before merging.
4. Unverified numeric claims in new opening paragraphs
intro.mdx: "20+ sources" — verify the exact count of source connectorsintro.mdx: "sub-20ms p99 query latency" — is this benchmarked? What workload? This is a marketing claim that could undermine trust if not accuratedelivery/overview.mdx: "30+ downstream systems" — verify the actual count
If these numbers aren't precisely documented, use softer language or link to the connectors page.
🟡 Suggestions (Non-blocking)
5. intro.mdx opening paragraph is very dense
The new opening paragraph is a single 60+ word sentence. For AEO it's better to have a self-contained answer, but it should still be readable. Consider breaking it into 2-3 shorter sentences.
6. architecture.mdx opening paragraph is now very long
The original "RisingWave has four main components..." was clean and scannable. The new version packs all four node types with descriptions into one sentence. The table right below already explains each node — consider keeping the opener shorter and letting the table do the heavy lifting.
7. sql/overview.mdx: mod → mode fix is good
This is a bug fix — the original had mod: wide which was likely a typo. Good catch, but worth calling out in the PR description since it's a functional fix, not just SEO.
8. Link validity — please verify these paths exist
[Memory management and tuning](/operate/memory-control)added infaq-using-risingwave.mdx[Apache Iceberg table engine](/iceberg/iceberg-table-engine)added infaq-when-to-use-risingwave.mdx
✅ What works well
- FAQ restructuring from nested Accordions to H2 + subsections is a major readability improvement
- Comparison tables in
faq-when-to-use-risingwave(streaming vs OLAP, MV comparison) are much better than the original wall-of-text <Note>blocks for important caveats (e.g., "reserved memory must be at least 512 MB")- Version history table for reserved memory is clearer than the nested Accordion approach
- Alt text additions are good for accessibility
- Card reordering in
faq-overview("When to use" before "Using") makes sense from a user journey perspective
Summary: Main blockers are (1) verify JSON-LD renders correctly in Mintlify, (2) trim titles/descriptions that exceed SERP display limits, and (3) verify numeric claims. The rest are polish items.
… content - Fix 2 broken links: /operate/memory-control → /operate/tune-reserved-memory, /iceberg/iceberg-table-engine → /iceberg/internal-iceberg-tables - Trim 9 titles that exceeded Google's ~60 char SERP display limit - Trim 4 descriptions that exceeded ~160 chars - Remove unverified "sub-20ms p99" performance claim from intro - Soften "20+" and "30+" connector count claims - Shorten dense opening paragraphs in intro.mdx and architecture.mdx - Fix "semi, anti" join terminology per Copilot review - Align "Iceberg table engine" terminology with existing docs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
Correction to my earlier review: Item #8 (link validity) — I listed incorrect paths. The actual links in the PR are:
All 10 internal links added/modified in this PR have been verified and are valid. No link issues. |
Summary
FAQPageJSON-LD structured data injected for Google Rich SnippetsPages modified (23)
faq-overview,faq-using-risingwave,faq-when-to-use-risingwaveintro,quickstart,architecture,source-table-mv-sink,use-casesoverview,cdc-with-risingwave,kafka,pg-cdc,mysql-cdcoverviewserve/overview,delivery/overviewsql-create-mv,sql/overviewkey-concepts,risingwave-flink-comparisonstore/overview,iceberg/overview,deploy/deployment-modes-overviewExpected SEO/AEO impact
Test plan
🤖 Generated with Claude Code