外观
PostgreSQL 文档规范
文档结构
文档分类
- 基础理论类：涵盖数据库核心概念、架构设计和工作原理
- 安装配置类：包括数据库安装、初始化和参数配置
- 运维管理类：涉及日常运维、监控告警和备份恢复
- 性能优化类：包含查询优化、索引设计和系统调优
- 高可用类：涵盖复制集群、故障转移和灾备设计
- 安全管理类：包括权限管理、加密和漏洞防护
- 故障处理类：涉及常见故障诊断和解决方案
- 迁移升级类：包括版本升级和数据迁移
- 扩展应用类：涵盖常用扩展和应用场景
文档层级
# 文档标题（一级标题）
## 章节标题（二级标题）
### 子章节标题（三级标题）
- 列表项 1
- 列表项 2
- 嵌套列表项
#### 四级标题（仅在必要时使用）禁止使用的章节
- 禁止使用"概述"、"总结"、"小结"等非实质性章节
- 禁止使用标题编号（如"1. 引言"、"2.1 概述"）
- 禁止使用英文标题（标题必须为中文）
内容要求
语言规范
- 使用中文编写所有内容：包括标题、正文、代码注释和图表说明
- 语言简洁明了：避免冗长复杂的句子结构
- 术语统一规范：使用行业标准术语，避免口语化表达
- 避免歧义：确保技术概念表达准确，无歧义
内容完整性
- 版本差异覆盖：明确说明不同PostgreSQL版本间的差异
- 生产实践：包含实际生产环境中的操作步骤和最佳实践
- 常见问题：每个文档必须包含FAQ部分，解答实际使用中的常见问题
- 代码示例：提供完整、可执行的代码示例，包含必要的注释
内容实用性
- 贴合实际生产场景：所有内容基于实际运维经验，避免理论脱离实际
- 操作步骤详细：提供清晰的操作步骤，包含命令示例和预期输出
- 风险提示：明确说明操作可能带来的风险和应对措施
- 性能影响：说明配置变更或操作对系统性能的影响
格式规范
头部信息
每个文档必须包含以下YAML格式的头部信息：
yaml
---
title: PostgreSQL 文档标题
description: 文档简要描述，用于SEO和页面元数据
keywords: 关键字1, 关键字2, 关键字3
---代码块
- 使用标准代码块格式：使用三个反引号包裹代码，并指定正确的语言
- 支持的代码语言：sql, bash, yaml, json, conf, txt等
- 代码注释：关键代码段必须包含中文注释
- 代码示例完整性：提供完整的可执行示例，包括前置条件和执行结果
图表规范
- 使用mermaid绘制图表：避免使用ASCII艺术图
- 图表标题：每个图表必须包含中文标题
- 图表清晰度：确保图表结构清晰，易于理解
- 图表编号：无需为图表添加编号
链接规范
- 内部链接：使用相对路径链接到其他文档
- 外部链接：必须使用完整URL，避免使用短链接
- 链接描述：链接文本必须清晰描述链接目标内容
版本管理
版本标识
- 文档版本：在文档中明确说明适用的PostgreSQL版本范围
- 变更记录：记录文档的主要变更历史
- 版本兼容性：明确说明不同版本间的兼容性差异
版本差异描述
对于不同版本间的差异，使用以下格式描述：
| 特性 | PostgreSQL 12 | PostgreSQL 13 | PostgreSQL 14 |
|------|---------------|---------------|---------------|
| 并行查询 | 支持 | 增强 | 进一步优化 |
| 逻辑复制 | 基础支持 | 增强 | 支持分区表 |质量要求
内容审核
- 准确性：确保所有技术内容准确无误
- 完整性：涵盖所有相关知识点和操作步骤
- 一致性：保持术语、格式和风格的一致性
- 实用性：内容对实际运维工作有指导意义
可读性
- 结构清晰：文档结构层次分明，便于导航
- 排版整洁：适当使用空白、列表和强调，提高可读性
- 重点突出：使用加粗、斜体等方式突出重点内容
- 易于搜索：合理设置关键词，提高文档可搜索性
最佳实践
文档编写流程
- 需求分析：明确文档的目标读者和核心内容
- 大纲设计：制定详细的文档大纲和结构
- 内容编写：按照大纲编写文档内容，确保完整性和准确性
- 代码测试：验证所有代码示例可正常执行
- 审核修改：进行内部审核和修改完善
- 发布更新：定期更新文档，反映版本变化和最佳实践
常见问题编写
- 问题典型性：选择用户最常遇到的问题
- 解答完整性：提供完整的解决方案，包括操作步骤和注意事项
- 问题分类：按照问题类型或场景进行分类
- 搜索优化：使用用户常用的搜索关键词
维护更新
- 定期更新：根据PostgreSQL版本发布和技术发展定期更新文档
- 反馈机制：建立文档反馈渠道，收集用户意见和建议
- 版本控制：使用版本控制系统管理文档变更
- 变更通知：重要变更及时通知相关用户
常见问题（FAQ）
Q1: 文档中可以使用英文缩写吗？
A1: 可以使用行业标准的英文缩写，但首次出现时必须标注中文全称。例如："WAL（Write-Ahead Logging，预写日志）"。
Q2: 如何处理不同PostgreSQL版本间的差异？
A2: 对于版本差异，应在文档中明确说明适用的版本范围，并使用表格或列表形式对比不同版本的特性差异。重要的版本差异应在相关章节中重点强调。
Q3: 文档中可以包含个人经验和见解吗？
A3: 可以，但必须明确区分客观事实和个人经验。个人经验应标注为"经验分享"或"最佳实践"，并说明适用场景和局限性。
Q4: 如何确保文档内容的准确性？
A4:
- 参考官方文档和权威资料
- 所有代码示例必须经过实际测试
- 邀请领域专家进行审核
- 建立反馈机制，及时修正错误
Q5: 文档长度有什么要求？
A5: 文档长度应根据内容需求而定，一般建议：
- 基础理论类文档：5000-10000字
- 操作指南类文档：3000-8000字
- 故障处理类文档：2000-5000字
关键是确保内容完整、结构清晰，避免冗余和不必要的信息。
Q6: 如何编写有效的FAQ部分？
A6:
- 从用户视角出发，使用用户常用的提问方式
- 问题应具有代表性和普遍性
- 解答应简洁明了，提供具体的操作步骤
- 按照问题类型或场景进行分类
Q7: 文档中可以使用截图吗？
A7: 可以，但应尽量使用文字描述和代码示例。截图仅在必要时使用，且必须清晰、相关，并配有适当的说明文字。
Q8: 如何处理文档的版本控制？
A8:
- 使用Git等版本控制系统管理文档变更
- 建立清晰的分支策略，区分不同版本的文档
- 为每个文档版本添加标签和发布说明
- 保留历史版本，便于查阅和比较
Q9: 文档更新频率是多少？
A9:
- 重大版本发布时：立即更新相关文档
- 安全漏洞修复时：及时更新安全相关文档
- 最佳实践变更时：定期更新相关文档
- 一般情况下：每季度或半年进行一次全面检查和更新
Q10: 如何提高文档的可搜索性？
A10:
- 合理设置文档标题和关键词
- 使用清晰的文档结构和层次
- 为重要内容添加适当的标签
- 确保文档内容与搜索关键词高度相关
- 定期更新文档，保持内容的时效性