Skip to content

STYLE_GUIDE.md

Latest commit

 

History

History
133 lines (84 loc) · 3.78 KB

STYLE_GUIDE.md

File metadata and controls

133 lines (84 loc) · 3.78 KB

Serverpod writing style guide

1. Write for technical, hands-on teams

Our audience is CTOs, lead developers, and Flutter teams building production apps. Write like a senior engineer talking to another senior engineer.

Rules:

  • Be clear and direct.
  • Avoid hype and vague claims.
  • Be specific and concrete.
  • Respect the reader’s intelligence.
  • Acknowledge real technical tradeoffs without exaggerating.

Examples:

Weak: The ultimate backend solution for modern apps.
Strong: Build your backend in Dart, deploy with zero configuration, and keep full control of your stack.

Weak: A powerful and robust platform.
Strong: An open-source backend framework for Flutter teams who want full-stack type safety in Dart.

Weak: Managing infrastructure is a nightmare.
Strong: Switching between Dart on the frontend and another language on the backend adds unnecessary cognitive load.

Weak: Supercharge your backend journey.
Strong: Deploy your backend without touching a single config file.

2. Terminology and naming consistency

  • Always capitalize Serverpod (proper noun).
  • Always write Serverpod Cloud with both words capitalized.
  • Always write the advocacy program as: Serverpod Voyager - Developer Expert Program (exact capitalization and hyphenation).
  • Use consistent core terminology: prefer “backend framework” or “full-stack Dart framework” over mixing with “platform,” “solution,” or “BaaS,” unless context clearly requires it. Prefer “open-source backend framework” when emphasizing positioning, and avoid inventing new category terms.

Canonical product phrases

Use these preferred terms consistently across the website, docs, and marketing:

  • “Type-safe APIs” (not “typed APIs” or “strongly typed endpoints”).
  • “Full-stack type safety” when referring to end-to-end Dart integration.
  • “Zero-configuration deployments” when referring to Serverpod Cloud.
  • “Streaming endpoints” for real-time functionality (not “real-time sockets” unless technically necessary).
  • “Modules” or “built-in modules” are used when describing reusable functionality.
  • “Open-source backend framework for Flutter” when positioning against alternatives.

Avoid introducing new labels for the same concepts unless there is a clear technical distinction.

3. Headlines

  • Use sentence case.
  • Do not capitalize every word.
  • Capitalize proper nouns only.

Correct:

  • Build your backend in Dart
  • Real-time features without the chaos
  • Why Flutter teams choose Serverpod

Incorrect:

  • Build Your Backend In Dart
  • Real-Time Features Without The Chaos

4. Oxford comma

Always use the Oxford comma in lists.

Correct: Authentication, streaming endpoints, and a built-in ORM.
Incorrect: Authentication, streaming endpoints and a built-in ORM.

5. Lists and periods

When bullet points are full sentences, end each one with a period.

Correct:

  • Serverpod is fully open source.
  • It offers zero-configuration deployments.
  • It provides type-safe APIs.

If bullet points are fragments, do not mix them with full sentences.

Correct:

  • Open source
  • Zero-configuration deployments
  • Type-safe APIs

Incorrect:

  • Open source
  • It offers zero-configuration deployments.
  • Type-safe APIs

6. Referring to other tools

  • Do not attack competitors.
  • Avoid emotional or dismissive language.
  • Position Serverpod through clarity and tradeoffs, not negativity.

Avoid: Firebase is broken and overpriced.
Prefer: If you want predictable pricing and open-source flexibility, Serverpod offers a compelling alternative.

7. Calls to action

Use calm, confident, and technical CTAs.

Good:

  • Get started with Serverpod.
  • Explore the documentation.
  • Deploy your first backend in minutes.

Avoid:

  • Don’t miss out!
  • Act now!
  • Limited time only!