跳到主要内容

如何为 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. 考虑维护

    • 在适当的地方使用版本号
    • 避免使用有时效性的引用
    • 在组织内容时考虑未来的更新

后续步骤​

阅读本指南后，您可以：

  • 使用提供的结构开始编写您自己的指南
  • 查看现有指南以供参考
  • 为您的指南请求唯一的标题图像
  • 提交您的指南以供审核

有关更多信息和更新：