Back to Details

documentation-guidelines

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Guidelines

文档指南

Overview

概述

Produce a single, canonical module doc that matches the repository's documentation rules and keeps backend/API contracts consistent and skimmable.
生成一份符合仓库文档规则的单一标准模块文档，确保后端/API契约一致且易于浏览。

Workflow

工作流程

  1. Locate the repo's documentation rules (prefer 
    docs/memories/DOCUMENTATION_GUIDELINES.md
    ). If missing, load 
    references/documentation-guidelines.md
    .
  2. Determine the correct documentation path for the current project. Use the repo's conventions; if no zones exist, default to 
    docs/features/<module>.md
    (or the project's documented location).
  3. Create or update the module doc before changing logic. Remove outdated content instead of appending.
  4. Follow the required section order from the guidelines and keep the doc in English.
  1. 查找仓库的文档规则（优先选择
    docs/memories/DOCUMENTATION_GUIDELINES.md
    ）。如果缺失，加载
    references/documentation-guidelines.md
    。
  2. 确定当前项目的正确文档路径。遵循仓库的约定；如果没有分区，默认使用
    docs/features/<module>.md
    （或项目指定的位置）。
  3. 在修改逻辑之前创建或更新模块文档。删除过时内容，而非追加。
  4. 遵循指南要求的章节顺序，文档保持英文撰写。

Required Content Checklist

必填内容清单

  • Start every doc with YAML frontmatter metadata (
    name
    , 
    description
    , 
    version
    , 
    last_updated
    , 
    maintained_by
    ), then write the rest as standard Markdown sections.
  • Include Mermaid ERD and Mermaid flowchart.
  • Document controllers/routes, requests, resources, models, services, jobs, and providers.
  • Provide endpoint table, headers, payloads, response examples, and error dictionary.
  • State permissions, feature flags, and client consumption rules.
  • Add local development + seeding commands and troubleshooting/log hints.
  • 每份文档开头需包含YAML前置元数据（
    name
    、
    description
    、
    version
    、
    last_updated
    、
    maintained_by
    ），其余部分采用标准Markdown章节撰写。
  • 包含Mermaid实体关系图（ERD）和Mermaid流程图。
  • 记录控制器/路由、请求、资源、模型、服务、任务和提供者。
  • 提供端点表格、请求头、负载、响应示例和错误字典。
  • 说明权限、功能标志和客户端使用规则。
  • 添加本地开发+数据填充命令以及故障排查/日志提示。

Style Rules

样式规则

  • Use frontmatter + Markdown consistently (no plain-text-only docs).
  • Describe contracts and behavior, not UI.
  • Use tables for endpoints and business rules.
  • Keep Mermaid labels short and safe; wrap special characters in quotes if needed.
  • Delete obsolete text to keep the doc clean and non-duplicative.
  • 始终一致使用前置元数据+Markdown格式（不允许纯文本文档）。
  • 描述契约和行为，而非用户界面。
  • 使用表格展示端点和业务规则。
  • 保持Mermaid标签简短安全；如有需要，将特殊字符用引号包裹。
  • 删除过时文本，保持文档简洁无重复。

Frontend API Documentation

前端API文档

If the user explicitly asks for frontend-facing API docs, load the repo's frontend guideline file (typically 
docs/memories/FRONTEND_API_DOCUMENTATION_GUIDELINES.md
) and follow it.
如果用户明确要求面向前端的API文档，加载仓库的前端指南文件（通常为
docs/memories/FRONTEND_API_DOCUMENTATION_GUIDELINES.md
）并遵循其规则。

Resources

资源

  • references/documentation-guidelines.md
    : Canonical structure and ordering for backend feature documentation.
  • references/documentation-guidelines.md
    ：后端功能文档的标准结构和顺序规范。