Feat 文档写作标准

关于文档

本文档是 Feat 框架的文档写作标准指南，旨在确保所有 AI 生成的文档具有一致性、专业性和易读性。

Feat 文档遵循”实践为主，原理为辅”的理念，优先介绍功能的实际应用，然后根据需要解释相关技术原理，帮助读者快速上手并解决实际问题。

1. 文档结构规范

1.1 基本结构

一篇标准的 Feat 技术文档应包含以下要素：

文档头部信息：包含标题、描述等元数据
引言部分：简要介绍文档主题和目标
主体内容：按逻辑顺序组织的技术内容
总结部分：概括要点或提供进一步学习指引
参考资料：相关链接和扩展阅读

1.2 文档头部信息

每篇文档必须包含标准的头部信息（Frontmatter）：

---
title: 文档标题
description: 简短描述文档内容
sidebar:
  order: 排序数字（可选）
---

1.3 标题层级规范

由于已存在文章title，无需使用 # 表示主标题（H1）
使用 ## 表示章节标题（H2）
使用 ### 表示小节标题（H3）
最多使用三级标题，避免更深的嵌套

1.4 内容组织原则

实践优先：优先介绍如何使用功能，提供实际可用的示例
原理补充：在读者了解基本用法后，适当解释背后的原理
循序渐进：从基础功能开始，逐步深入高级特性
实例驱动：通过具体示例演示功能的使用方法

2. 语言风格标准

2.1 语言风格要求

为了使文档更具亲和力和可读性，应遵循以下语言风格要求：

使用亲切自然的语调，就像技术专家在与读者面对面交流
避免机械生硬、缺乏情感的表达，适当使用生活化、具象化的词汇
在恰当处融入轻松语气，但不影响技术内容的严谨性

2.2 叙述方式

采用以下叙述方式可以提高文档的可读性：

采用引导式叙述，如”让我们一起来实现一个简单的HTTP服务器”
善用设问句引发读者思考，如”你是否想过这个功能是如何实现的？”
适当使用修辞手法，让抽象的技术概念更易于理解

2.3 情感表达

适当的情感表达可以增强读者的阅读体验：

在适当时机表达对技术的热情，如”这个特性真是太棒了”
对于复杂概念给予读者鼓励，如”别担心，我们一起慢慢来”
体现对读者学习进度的关心，如”掌握了这些基础，你就能轻松应对大部分场景了”

2.4 互动性增强

增强文档的互动性有助于提高读者参与度：

多使用”我们”、“你”等人称代词，营造共同学习的氛围
在关键知识点处设置提醒，如”这里有个小细节需要注意”
在段落结尾适当提出启发性问题，激发读者思考

3. 技术内容标准

3.1 代码示例规范

代码示例是技术文档的重要组成部分，应遵循以下规范：

每段代码示例必须配有简要说明，重点说明用途和使用方法
重要的代码行应添加注释，特别是关键参数和配置项
示例代码应具备完整性和可执行性
突出实践：优先展示功能的具体应用场景，而非理论框架
简化示例：仅展示与当前讨论主题相关的核心代码，避免冗长的样板代码
使用适当的语法高亮标记
代码验证：所有代码示例必须基于项目实际源码，确保与项目实际情况完全一致，不得出现任何虚构或不正确的代码片段

// 实践导向的示例：展示如何创建HTTP服务
public class HttpServerExample {
    public static void main(String[] args) {
        // 创建HTTP服务器并监听8081端口
        Feat.httpServer()
                .httpHandler(request -> {
                    // 处理HTTP请求，返回"Hello World"响应
                    request.getResponse().write("Hello World");
                })
                .listen(8081);
    }
}
// 注：省略了不影响理解的样板代码

所有代码示例都应该链接到 Gitee 仓库中的实际文件，以便读者可以查看完整的上下文和运行示例。例如：

有关完整示例，请参见 HelloWorld.java

3.2 功能实践与原理解析

在文档编写过程中，应按照以下方式平衡功能实践和原理解析：

实践优先原则：

首先介绍功能的作用和使用场景
提供可直接运行的代码示例
说明常见配置选项及其效果

原理补充原则：

在读者掌握基本用法后，适时解释工作原理
通过图表等方式直观展示内部机制
避免一开始就陷入复杂的理论讲解

层次化内容组织：

基础用法部分：专注于”怎么做”
进阶用法部分：解释”为什么这样做”
工作原理解析：深入探讨”它是如何工作的”

3.3 图表使用规范

首选 Mermaid：对于流程图、架构图等，优先使用 Mermaid 语法
复杂图表使用通道图：对于复杂的系统交互图、数据流图等，优先使用通道图进行表达
图表应有明确的标题和说明文字
图片文件应存储在相应的 img 目录中
使用相对路径引用图片
使用 Mermaid 时，必须在文档顶部导入自定义组件：import Mermaid from '../../../components/Mermaid.astro';

3.3.1 Mermaid 图表规范

为了生成高质量的 Mermaid 图表，请遵循以下规范：

图表结构要求：
- 使用清晰的节点命名，避免使用无意义的字母
- 节点文本应简洁明了，不超过一行
- 连接线应有明确含义，必要时添加标签
- 保持图表布局整洁，避免线条交叉
图表类型选择：
- 流程图：graph TD 或 graph LR 用于表示执行流程
- 序列图：sequenceDiagram 用于表示对象间交互
- 类图：classDiagram 用于表示类关系
- 状态图：stateDiagram 用于表示状态变化
- 组件图：graph TD 用于表示系统组件关系
节点样式规范：
- 方形节点：A[节点文本]
- 圆形节点：A((节点文本))
- 菱形节点：A{条件判断}
- 圆角矩形：A(节点文本)
图表设计原则：
- 一致性：同一文档中相同类型的元素应使用相同的样式
- 可读性：确保节点文本清晰可见，避免过长文本
- 逻辑性：图表流向应符合常规阅读习惯（从上到下或从左到右）
- 简洁性：只包含必要的信息，避免图表过于复杂
Mermaid 图表样式风格约束：

为了确保 Feat 文档中所有 Mermaid 图表具有一致的视觉风格和专业外观，特制定以下样式约束：

颜色规范：

默认使用黑白配色方案，确保打印和屏幕显示效果一致
如需使用颜色，应遵循 Feat 品牌色彩规范：主色调为蓝色 (#2196F3)
不同类型的节点应通过形状区分，而非颜色区分
连接线使用黑色，默认宽度为 1px

字体规范：

节点文本使用与文档正文一致的字体
字号应适中，确保在不同设备上都能清晰阅读
避免使用特殊字体效果（如斜体、下划线等）
文本对齐方式统一采用居中对齐

间距与布局规范：

节点之间应保持适当间距，避免过于拥挤或分散
图表整体应居中布局，避免偏向一侧
连接线应尽量保持直线，避免不必要的弯曲
当无法避免连线交叉时，应使用桥接符号明确表示

响应式设计规范：

图表应能在不同屏幕尺寸下正常显示
避免创建过大的图表，单个图表宽度不应超过 800px
对于复杂图表，应考虑拆分为多个子图表
移动端显示时，图表应能自适应缩放

高质量示例：

流程图示例：

<Mermaid code={`
graph TD
    A[用户请求] --> B{身份验证}
    B -->|验证成功| C[处理请求]
    B -->|验证失败| D[返回错误]
    C --> E[返回结果]
    D --> E
`} />

序列图示例：

<Mermaid code={`
sequenceDiagram
    participant U as 用户
    participant S as 服务器
    participant D as 数据库

    U->>S: 登录请求
    S->>D: 验证凭据
    D-->>S: 验证结果
    S-->>U: 登录响应
`} />

类图示例：

<Mermaid code={`
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }

    class Dog {
        +String breed
        +bark()
    }

    class Cat {
        +String color
        +meow()
    }

    Animal <|-- Dog
    Animal <|-- Cat
`} />

组件图示例：

<Mermaid code={`
graph TD
    A[客户端] --> B(负载均衡器)
    B --> C[Web服务器1]
    B --> D[Web服务器2]
    B --> E[Web服务器3]
    C --> F[(数据库)]
    D --> F
    E --> F
`} />

在使用 Mermaid 图表之前，需要在文档顶部导入自定义的 Mermaid 组件：

import Mermaid from '../../../components/Mermaid.astro';

然后在文档正文中使用 Mermaid 组件：

<Mermaid code={`
graph TD
    A[开始] --> B[处理]
    B --> C[结束]
`} />

3.3.2 通道图使用规范

对于复杂的系统架构图、数据流图等，应优先考虑使用通道图（Channel Diagram）：

适用场景：
- 复杂的系统交互图
- 多组件数据流图
- 高并发处理流程图
- 网络通信架构图
设计原则：
- 清晰表达数据流向和处理节点
- 合理划分通道和处理单元
- 保持整体结构简洁易懂
示例：

<Mermaid code={`
graph LR
    A[数据源] --> B{通道1}
    B --> C[处理器1]
    C --> D{通道2}
    D --> E[处理器2]
    E --> F[结果输出]
`} />

3.3.3 架构设计图要求

对于相对复杂的功能，必须提供架构设计图，以便读者更好地理解系统的整体结构和各组件之间的关系：

架构图内容要求：
- 展示系统的核心组件
- 明确组件间的依赖关系
- 标注数据流向
- 说明关键接口和协议
架构图绘制规范：
- 使用标准的图形符号（矩形表示组件，箭头表示关系）
- 保持布局清晰，避免线条交叉
- 添加必要的文字说明和图例
- 为复杂系统提供分层视图
架构图示例：

<Mermaid code={`
graph TB
    A[客户端] --> B[API网关]
    B --> C[认证服务]
    B --> D[业务服务]
    B --> E[数据存储]
    C --> F[(用户数据库)]
    D --> F
    D --> G[(业务数据库)]
`} />

4. 格式排版规范

4.1 强调样式

加粗：用于强调关键词或重要概念
斜体：用于首次提及的术语或书籍名称
代码：用于行内代码或命令，注意格式正确性:”```“

4.2 列表使用

有序列表用于步骤说明
无序列表用于列举要点
列表项应保持平行结构

4.3 表格规范

表头使用简洁明确的标签
表格内容应左对齐
表格前后应有说明文字

5. 特殊内容处理

5.1 注意事项与警告

对于需要特别提醒的内容，使用专门的提示框：

6. AI 写作指导原则

为确保 AI 生成的文档既专业又具有良好的可读性，需要遵循以下指导原则：

6.1 内容准确性

确保功能使用说明的准确性
基于 Feat 项目实际情况进行描述
优先验证实践示例的正确性
避免推测性内容
所有代码示例必须与项目实际源码保持一致，禁止虚构代码

6.2 写作规范

严格遵循本文档规定的格式和风格
保持语言表达的一致性
确保文档结构清晰

6.3 上下文理解

准确理解用户查询意图，重点关注功能使用需求
结合 Feat 框架特点进行阐述，突出实用性
考虑目标读者的技术水平，提供合适的实践指导

7. 文档质量检查清单

在完成文档编写后，请对照以下清单进行检查：

通过遵循以上标准，AI 编写的 Feat 文档将更加专业、一致且易于理解，有助于提升整个项目的文档质量和用户体验。

8. 总结

本文档为 Feat 框架的 AI 文档生成提供了全面的指导原则。通过遵循这些规范，AI 可以生成高质量、一致性强且易于理解的技术文档。记住始终以用户需求为中心，注重实用性，并保持内容的准确性和时效性。