Back to Details

readme

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

README Guidelines

README 编写指南

Each top-level package directory (e.g., 
plain-api/
) has a 
README.md
symlink pointing to the actual README inside the package (e.g., 
plain-api/plain/api/README.md
). Only edit the README inside the package itself.
See 
plain-jobs/plain/jobs/README.md
 as a good example.
每个顶层包目录（例如 
plain-api/
）都有一个 
README.md
符号链接，指向包内部的实际README文件（例如 
plain-api/plain/api/README.md
）。仅编辑包内部的README文件。
可参考 
plain-jobs/plain/jobs/README.md
 作为优秀示例。

Purpose

目的

The README answers: "How do I use this?" It gets users productive quickly and points them to code for deeper exploration. It is not a complete API reference.
README需要回答：“我该如何使用这个包？” 它要帮助用户快速上手，并引导他们查看代码以进行深入探索。它并非完整的API参考文档。

Required Structure

必备结构

Every README follows this order:
  1. h1 with package name
  2. Bold one-liner describing the package
  3. Table of contents with links to h2s and h3s
  4. Overview section with basic working examples
  5. Feature sections as needed
  6. FAQs section (second to last) using h4s for questions
  7. Installation section (always last)
所有README都需遵循以下顺序：
  1. 一级标题（h1）：包名称
  2. 加粗单行描述：包的简介
  3. 目录：包含指向二级和三级标题的链接
  4. 概述部分：包含基础可运行示例
  5. 功能模块部分：按需添加
  6. **常见问题（FAQs）**部分：倒数第二部分，使用四级标题（h4）作为问题
  7. 安装部分：始终放在最后

Style

风格规范

  • Conversational tone: "You can..." not "The module provides..."
  • First code example must be copy-paste ready with imports included
  • Subsequent examples can be minimal, building on what was shown
  • Link to source for advanced features: 
    [ClassName](./file.py#ClassName)
  • Cross-package references: 
    [plain.auth](../../plain-auth/plain/auth/README.md)
  • 口语化语气：使用“你可以……”而非“该模块提供……”
  • 首个代码示例必须可直接复制粘贴使用，包含导入语句
  • 后续示例可简化，基于前面展示的内容扩展
  • 高级功能链接至源码：
    [ClassName](./file.py#ClassName)
  • 跨包引用：
    [plain.auth](../../plain-auth/plain/auth/README.md)

What to Document

需记录的内容

  • If users import it, document it
  • Mention all public features, even advanced ones briefly, then link to code
  • Internal APIs stay undocumented (
    _prefix
    functions and 
    @internalcode
    )
  • Don't fully document every parameter - mention features exist, link to code
  • 只要用户会导入的内容，都需要记录
  • 提及所有公开功能，即使是高级功能也要简要说明，然后链接至代码
  • 内部API无需记录（带有
    _
    前缀的函数和
    @internalcode
    装饰的内容）
  • 无需详细记录每个参数——只需说明功能存在，然后链接至代码

Writing Tips

编写技巧

  • Keep paragraphs short
  • Put takeaways up front
  • Use bullets and tables
  • Bold important text
  • Keep sentences simple and unambiguous
  • 段落简短
  • 重点内容前置
  • 使用项目符号和表格
  • 重要文本加粗
  • 句子简洁明确