跳到主要內容

如何撰寫 Prisma ORM 的指南

簡介​

本指南將說明如何撰寫 Prisma ORM 文件指南。它涵蓋了所需的結構、格式和樣式慣例，以確保所有指南的一致性。您將了解 frontmatter 的要求、章節組織和寫作風格。

先決條件​

在撰寫指南之前，請確保您已具備：

  • 清楚了解您所撰寫的主題
  • 存取 Prisma 文件儲存庫的權限
  • 熟悉 Markdown 和 MDX
  • 了解您的指南的目標受眾

指南結構​

必要的 frontmatter​

每個指南都必須在檔案頂部包含以下 frontmatter：

---
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：應該是行動導向的，並以「如何」開頭
  • metaTitle：通常與標題相符，用於 SEO
  • description：以「了解如何」開頭的單句摘要，用於 SEO
  • sidebar_label：側邊欄導覽的簡潔標籤
  • image：用於社群媒體分享的獨特標頭圖片（請與設計團隊協調）

所有 frontmatter 欄位都應使用句子大小寫，除了 image。

必要的章節​

  1. 簡介

    • 簡要概述指南涵蓋的內容
    • 讀者將學到/完成什麼
    • 連結到任何範例儲存庫或相關資源

  2. 先決條件

    • 必要的軟體/工具，包含版本號
    • 必要的知識/經驗
    • 任何必要的帳戶或存取權

  3. 主要內容章節

    • 程序性指南的編號步驟（例如，「1. 設定專案」）
    • 使用 H2 (##) 作為主要章節的清晰層次結構
    • 使用 H3 (###) 作為子章節
    • 每個步驟都應建立在先前的步驟之上

  4. 後續步驟

    • 完成指南後該做什麼
    • 相關指南或文件
    • 其他資源的連結
    • 社群資源（例如，Discord）

寫作風格和語氣​

一般原則​

  • 使用清晰、對話式的語氣撰寫
  • 使用主動語態和現在時
  • 使用「您」直接稱呼讀者
  • 在引導讀者完成步驟時，使用第一人稱複數（「我們」）
  • 避免使用行話，並解釋技術術語
  • 簡潔但詳盡

程式碼範例​

  • 包含完整、可執行的程式碼範例
  • 使用語法高亮顯示並指定語言
  • 在程式碼區塊中包含檔案路徑元資料
  • 使用註解來解釋複雜的部分
  • 在適用的情況下，同時顯示問題和解決方案

範例

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

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

格式慣例​

  • 使用反引號來表示：
    • 檔案名稱：`schema.prisma`
    • 目錄名稱：`prisma/`
    • 程式碼元素：`PrismaClient`
    • 指令：`npx prisma generate`
  • 使用 附註 來表示重要的註釋、警告、提示等。 
    :::note
    Important information goes here
    :::
  • 使用正確的標題層次結構（永遠不要跳過層級）
  • 在較長的程式碼區塊中包含行號
  • 針對替代方法使用標籤式內容

現有指南的範例​

遷移指南格式​

遷移指南遵循特定的模式，如 從 Sequelize 遷移 和 從 Mongoose 遷移 等指南中所見

  1. 清楚的簡介，說明遷移路徑
  2. 針對兩種 ORM 的特定先決條件
  3. 逐步的遷移過程
  4. 兩種 ORM 之間的程式碼比較
  5. 常見操作的實用範例

整合指南格式​

整合指南（如 將 Prisma ORM 與 Cloudflare D1 一起使用）著重於：

  1. 設定和組態
  2. 平台特定的考量
  3. 逐步實作
  4. 部署說明
  5. 平台特定的最佳實務

最佳實務​

  1. 保持重點

    • 每個指南應涵蓋一個主要主題
    • 將複雜的主題分解為多個指南
    • 連結到相關指南，而不是複製內容

  2. 示範而非說明

    • 包含實用的真實範例
    • 提供完整、可運作的程式碼範例
    • 解釋為什麼建議採用某些方法

  3. 考慮情境

    • 清楚地解釋先決條件
    • 不要假設讀者具備先前的知識
    • 在需要時連結到我們文件內或外的基礎概念

  4. 維持一致性

    • 遵循已建立的指南結構
    • 使用一致的術語
    • 與現有指南的風格相符

  5. 考慮維護

    • 在適用的情況下使用版本號碼
    • 避免使用有時間敏感性的參考
    • 在組織內容時考慮未來的更新

後續步驟​

閱讀本指南後，您可以：

  • 使用提供的結構開始撰寫您自己的指南
  • 參考現有指南
  • 為您的指南請求獨特的標頭圖片
  • 提交您的指南以進行審閱

如需更多資訊和更新：