Skip to content

docs: Overview - removed all redundant info and reworked it's purpose#457

Open
Swiftaxe wants to merge 2 commits intomainfrom
feat/overview-reworked
Open

docs: Overview - removed all redundant info and reworked it's purpose#457
Swiftaxe wants to merge 2 commits intomainfrom
feat/overview-reworked

Conversation

@Swiftaxe
Copy link
Copy Markdown
Contributor

@Swiftaxe Swiftaxe commented Apr 2, 2026

Overview page rewrite

This PR strips the redundant content and rewrites the page as a genuine architectural explanation.

Problem

The Overview page (docs/02-overview.md) was largely redundant with two other pages:

  • Introduction (index.md) — already lists Serverpod's key capabilities and features with nearly identical wording.
  • Get started (01-get-started/) — already covers endpoints, models, and database usage hands-on, with the same code examples the Overview was repeating.

A Diataxis analysis identified the page as an "Explanation attempt" that failed its purpose: instead of explaining how Serverpod works conceptually, it restated marketing bullets and duplicated tutorial code. The endpoint example appeared in three separate places (index.md, 02-overview.md, and the get-started tutorial).

On the other hand, no page in the docs explained:

  • Three-package project structure (server, client, flutter).
  • The code generation pipeline.
  • The request lifecycle.
  • The role of Session.

All these things are essential for a user to understand to work confidently with Serverpod.

Solution

  • Step 1 — Remove the intro paragraph. Near-exact duplicate of index.md. Removed.
  • Step 2 — Remove the "Key capabilities" section. Near-exact duplicate of the feature bullets on index.md. Removed.
  • Step 3 — Remove the "Defining Endpoints" section. Tutorial content (endpoint class + client call code) that duplicates index.md and the get-started tutorial. Removed.
  • Step 4 — Remove the "Data Models and Serialization" section. Tutorial content that duplicates get-started step 2. Removed.
  • Step 5 — Remove the "Database Integration and ORM" section. Tutorial content that duplicates get-started step 3. Removed.
  • Step 6 — Remove the "Conclusion" section. Nothing in the Conclusion belongs in an architectural explanation page.
  • Step 7 — Rename the page. sidebar_label → "How it works", heading → "# How Serverpod works".
  • Step 8 — Add project structure section. Explains the three packages, what each owns, and why _client is never edited by hand.
  • Step 9 — Add code generation section. Explains what serverpod generate reads and produces. Includes a Mermaid flowchart.
  • Step 10 — Add request lifecycle section. Explains the call path from Flutter app to endpoint and back. Includes a Mermaid sequence diagram.
  • Step 11 — Add type-safety section. Explains .spy.yaml as the single source of truth and what that means for compile-time safety.

@Swiftaxe Swiftaxe changed the title Overview page - removed all redundant info and reworked it's purpose docs: Overview page: removed all redundant info and reworked it's purpose Apr 2, 2026
@Swiftaxe Swiftaxe changed the title docs: Overview page: removed all redundant info and reworked it's purpose docs: Overview - removed all redundant info and reworked it's purpose Apr 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant