文档目录 (/docs)

相关源文件

• README.md
• README_ro.md
• docs/README.md

Go项目中的/docs目录用于存储全面的设计和用户文档。它补充了从代码注释自动生成的API文档，并作为项目文档的中央存储库，其内容超出简单的代码解释。

有关示例和示例代码的信息，请参阅示例目录 (/examples)。有关API规范的信息，请参阅API目录 (/api)。

在项目结构中的作用和目的

在Go项目中，/docs目录是所有手动创建的项目文档的中心位置。与通过godoc或go doc自动生成的代码注释文档不同，/docs目录包含由开发人员独立维护的详细文档。

来源：README.md152-154 docs/README.md1-3

文档类型和组织

根据项目的需求，/docs目录通常包含各种类型的文档，可以组织成逻辑子目录。

文档类型	描述	典型位置
设计文档	系统架构，组件交互	/docs/design/
用户手册	终端用户说明和指南	/docs/user/
开发者指南	对贡献开发者的说明	/docs/dev/
API参考	扩展API文档	/docs/api/
决策记录	架构决策记录 (ADRs)	/docs/decisions/
图像	图表、截图、插图	/docs/images/

这种组织方式有助于在不同类型的文档之间保持清晰的界限，并确保它们易于被不同的利益相关者找到。

来源：docs/README.md3-4

文档工作流程和集成

应与代码更改一起维护/docs目录中的文档，以确保其准确性和时效性。此图说明了文档如何融入开发工作流程。

来源：README.md152-154

与Go文档系统的关系

Go项目通常采用多种文档方法，共同为不同受众提供全面的信息。

/docs目录通过提供以下内容来补充自动生成的Go文档：

1. 高级架构概览
2. 设计原理和决策
3. 扩展使用教程
4. 图表和截图等视觉辅助工具
5. 面向用户的文档

来源：README.md152-154 README.md203-205

真实Go项目中的示例

一些著名的Go项目有效地使用了/docs目录。

项目	文档结构	值得注意的方面
Hugo	github.com/gohugoio/hugo/tree/master/docs	广泛的用户指南和开发者文档
OpenShift	github.com/openshift/origin/tree/master/docs	架构文档和操作指南
Dapr	github.com/dapr/dapr/tree/master/docs	API规范和组件文档

这些示例说明了如何使用/docs目录来维护全面的文档，为用户和开发者服务。

来源：docs/README.md5-9

文档格式和工具

/docs目录通常包含以下格式的文档：

1. Markdown (.md) - 由于其简洁性和GitHub/GitLab的渲染能力，最为常用。
2. AsciiDoc (.adoc) - 适用于更复杂的文档需求。
3. PlantUML 或 Mermaid 图表 - 用于可视化表示。
4. 图片 (PNG, SVG) - 用于截图和自定义图表。
5. HTML - 适用于更复杂的格式化需求。

许多项目使用文档生成工具，如：

• Hugo - 用于文档站点的静态站点生成器。
• MkDocs - 简单的基于Markdown的文档站点生成器。
• Docusaurus - 用于创建文档站点。

这些工具可以将/docs目录的内容转换为可浏览的文档网站。

来源：docs/README.md3-4

最佳实践

在使用/docs目录时，请考虑以下最佳实践：

1. 将文档与代码保持接近，但要与实现细节分开。
2. 在整个文档中使用一致的格式和组织。
3. 包含图表来解释复杂的系统或工作流程。
4. 在同一个拉取请求中，随代码更改一起更新文档。
5. 在相关的文档部分之间使用交叉引用。
6. 考虑文档的受众及其技术专长。
7. 包含文档索引或导航指南。

遵循这些实践可以确保文档作为理解和使用项目宝贵的资源。

来源：README.md152-154 docs/README.md1-9