# 文档贡献

文档是rhosocial ActiveRecord的关键部分。良好的文档使项目更易于访问和使用。本指南将帮助您为我们的文档做出贡献。

## 文档贡献类型

您可以通过几种方式为文档做出贡献：

1. **API文档**：改进代码中的文档字符串
2. **用户指南**：增强`/docs`目录中的指南
3. **教程**：为特定用例创建分步教程
4. **示例**：添加演示功能的示例代码
5. **翻译**：将文档翻译成其他语言

## 文档贡献入门

1. **确定需要改进的领域**：
   - 寻找不清晰或缺失的文档
   - 检查过时的信息
   - 考虑在学习时哪些文档会对您有所帮助

2. **Fork和克隆**：按照[开发流程](development_process.md)设置您的环境。

3. **定位文档文件**：
   - 代码文档字符串位于源文件中
   - 用户指南位于`/docs`目录中
   - README和其他markdown文件位于仓库根目录中

## 文档标准

在为文档做出贡献时，请遵循以下标准：

- **清晰的语言**：使用简单、直接的语言
- **一致性**：保持一致的风格和术语
- **示例**：为复杂概念包含代码示例
- **结构**：使用标题、列表和其他格式来组织内容
- **完整性**：涵盖所有参数、返回值和异常

## 文档字符串指南

对于Python代码文档字符串：

- 遵循[Google风格](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)的文档字符串
- 在文档字符串中包含类型提示
- 记录参数、返回值和异常
- 为复杂函数提供示例

示例：
```python
def find_by_id(id: int) -> Optional[Model]:
    """通过ID查找模型实例。

    Args:
        id: 要查找的模型的唯一标识符。

    Returns:
        如果找到匹配的模型，则返回模型实例，否则返回None。

    Raises:
        ConnectionError: 如果数据库连接失败。

    Example:
        >>> user = User.find_by_id(123)
        >>> if user:
        ...     print(user.name)
    """
```

## 用户指南贡献

为用户指南做出贡献时：

1. **遵循现有结构**：保持与现有文档一致的格式和组织
2. **面向用户**：从用户的角度编写，关注如何使用功能
3. **包含实际示例**：提供可以复制和粘贴的工作代码
4. **解释为什么**：不仅说明如何做某事，还要解释为什么这是最佳方法

## 翻译指南

翻译文档时：

1. **保持技术准确性**：确保技术术语正确翻译
2. **考虑文化背景**：适应目标语言的文化和习惯
3. **保持一致的术语**：为技术术语创建和使用一致的术语表
4. **审查翻译**：如果可能，请其他人审查您的翻译
5. **翻译目录命名规范**：
   - 遵循ISO 639最新修订版标准
   - 语言代码使用小写（如`zh`、`en`）
   - 国家/地区代码使用大写（如`CN`、`US`）
   - 语言和国家/地区代码之间使用下划线分隔（如`zh_CN`、`en_US`）
6. **代码注释和消息**：
   - 代码中的注释、日志信息和异常信息目前仅使用英文
   - 除非是专门为特定地区或语言设置的特性

## 提交文档更改

1. **使用docs分支**：文档完善应当只尝试向docs分支提交
2. **限制更改范围**：
   - 只能修改`docs/`目录内的文件
   - 不能包含可执行脚本、二进制文件等
3. **提交更改**：使用描述性提交消息，例如"docs: 改进模型关系文档"
4. **创建拉取请求**：遵循与代码贡献相同的流程

## 文档审查流程

文档贡献将由维护者审查，他们将检查：

- 技术准确性
- 清晰度和可读性
- 语法和拼写
- 与现有文档的一致性

## 文档工具

我们使用以下工具来生成和维护文档：

- **Markdown**：用于大多数文档
- **Sphinx**：用于API文档生成
- **Read the Docs**：用于托管文档

## 文档最佳实践

- **保持更新**：当代码更改时更新相关文档
- **链接相关内容**：在文档部分之间创建交叉引用
- **使用截图和图表**：对于复杂概念，视觉辅助工具很有帮助
- **考虑可访问性**：确保文档对所有用户可访问

感谢您帮助改进rhosocial ActiveRecord的文档！良好的文档对于项目的成功至关重要。