Skip to main content

How to write guides for Prisma ORM

Introduction​

This guide shows you how to write guides for Prisma ORM documentation. It covers the required structure, formatting, and style conventions to ensure consistency across all guides. You'll learn about frontmatter requirements, section organization, and writing style.

Prerequisites​

Before writing a guide, make sure you have:

  • A clear understanding of the topic you're writing about
  • Access to the Prisma documentation repository
  • Familiarity with Markdown and MDX
  • Knowledge of the target audience for your guide

Guide structure​

Required frontmatter​

Every guide must include the following frontmatter at the top of the file:

---
title: 'How to [do something] with Prisma ORM'
metaTitle: 'How to [do something] with Prisma ORM'
description: 'Learn how to [do something] with Prisma ORM'
sidebar_label: '[Concise Label]'
image: '/img/guides/[guide-name]-cover.png'
---
  • title: Should be action-oriented and start with "How to"
  • metaTitle: Usually matches the title, used for SEO
  • description: A one-sentence summary starting with "Learn how to", used for SEO
  • sidebar_label: A concise label for the sidebar navigation
  • image: A unique header image for social media sharing (coordinate with the design team)

All frontmatter fields should be in sentence case, except for image.

Required sections​

  1. Introduction

    • Brief overview of what the guide covers
    • What the reader will learn/accomplish
    • Link to any example repositories or related resources

  2. Prerequisites

    • Required software/tools with version numbers
    • Required knowledge/experience
    • Any necessary accounts or access

  3. Main content sections

    • Numbered steps for procedural guides (e.g., "1. Set up the project")
    • Clear hierarchy with H2 (##) for main sections
    • H3 (###) for subsections
    • Each step should build on previous steps

  4. Next steps

    • What to do after completing the guide
    • Related guides or documentation
    • Links to additional resources
    • Community resources (e.g., Discord)

Writing style and voice​

General principles​

  • Write in a clear, conversational tone
  • Use active voice and present tense
  • Address the reader directly using "you"
  • Use first person plural ("we") when guiding the reader through steps
  • Avoid jargon and explain technical terms
  • Be concise but thorough

Code examples​

  • Include complete, runnable code examples
  • Use syntax highlighting with language specification
  • Include file paths in code block metadata
  • Use comments to explain complex parts
  • Show both the problem and solution when applicable

Example:

src/index.ts
// Import required dependencies
import { PrismaClient } from '@prisma/client'

// Initialize Prisma Client
const prisma = new PrismaClient()

Formatting conventions​

  • Use backticks for:
    • File names: `schema.prisma`
    • Directory names: `prisma/`
    • Code elements: `PrismaClient`
    • Commands: `npx prisma generate`
  • Use admonitions for important notes, warnings, tips, etc.: 
    :::note
    Important information goes here
    :::
  • Use proper heading hierarchy (never skip levels)
  • Include line numbers in longer code blocks
  • Use tabbed content for alternative approaches

Examples from existing guides​

Migration guide format​

Migration guides follow a specific pattern, as seen in guides like Migrate from Sequelize and Migrate from Mongoose:

  1. Clear introduction explaining the migration path
  2. Prerequisites specific to both ORMs
  3. Step-by-step migration process
  4. Code comparison between ORMs
  5. Practical examples of common operations

Integration guide format​

Integration guides, like Using Prisma ORM with Cloudflare D1, focus on:

  1. Setup and configuration
  2. Platform-specific considerations
  3. Step-by-step implementation
  4. Deployment instructions
  5. Platform-specific best practices

Best practices​

  1. Keep it focused

    • Each guide should cover one main topic
    • Break complex topics into multiple guides
    • Link to related guides instead of duplicating content

  2. Show don't tell

    • Include practical, real-world examples
    • Provide complete, working code samples
    • Explain why certain approaches are recommended

  3. Consider the context

    • Explain prerequisites clearly
    • Don't assume prior knowledge
    • Link to foundational concepts within or outside of our docs when needed

  4. Maintain consistency

    • Follow the established guide structure
    • Use consistent terminology
    • Match the style of existing guides

  5. Think about maintenance

    • Use version numbers where appropriate
    • Avoid time-sensitive references
    • Consider future updates when structuring content

Next steps​

After reading this guide, you can:

  • Start writing your own guide using the provided structure
  • Review existing guides for reference
  • Request a unique header image for your guide
  • Submit your guide for review

For more information and updates: