文档 作家工具包 入门

开始撰写文档

本指南包含完成文档项目的全部所需内容，从开始到结束。

目标

本指南

• 教您如何成功地记录产品和功能
• 提供从项目启动到发布的循序渐进指南
• 向您介绍创建优质文档的技巧

受众

• 需要在编写代码的同时创建文档的软件开发人员
• 创建并贡献文档的其他技术岗位

开始之前

• 思考您希望阅读文档的人理解或完成什么

项目清单

如果您有问题

• 如果您是 Grafana Labs 的员工，请在内部 Slack 工作区的 #docs 频道联系我们。
• 如果您不是 Grafana Labs 的员工，请在社区 Slack 工作区的 #docs 频道联系我们。

如何开始

1. 规划工作
2. 创建结构
3. 起草文档
4. 审阅文档
5. 发布文档

规划工作

1. 确定您需要哪种文档交付物。您希望用户完成什么？

2. 了解产品或功能的发布生命周期阶段。查阅Grafana Labs 发布周期。

创建结构

1. 将文档添加到您的 GitHub 仓库。如果尚不存在，请在您的仓库中添加一个 docs/sources 目录。

2. 创建文件夹和结构。使用内容框架来确保产品文档的一致性。有关内容框架的更多信息，请参阅文档结构。

起草文档

1. 了解如何最好地撰写和组织文档。阅读作家工具包中的主题类型主题和子主题。

2. 添加前置信息。阅读前置信息文档。

3. 添加图片和媒体。阅读图片、图表、截图和视频指南文档。

4. 使用链接。请参考链接文档。

5. 添加代码示例。要使用 Markdown 添加示例，请参考代码块。有关风格指南，请参考代码示例。对于多种语言的示例，请参考代码。

6. 请参考风格约定。

审阅文档

1. 在本地构建文档。有关说明，请参考测试文档更改。
2. 打开一个 Pull Request 并使用标签 type/docs。
3. 使用 Vale 文本 linter。这些通常是 PR 内部的自动检查。要了解有关 Vale 文本 linter 的更多信息，请参考使用 Vale linter 进行文本 Lint。

发布文档

1. 审阅发布选项。如果您是 Grafana Labs 的员工，请在内部 Slack 工作区的 #docs 频道联系我们。如果您不是 Grafana Labs 的员工，请在社区 Slack 工作区的 #docs 频道联系我们。
2. 如果需要，请进行反向移植。有关指导，请参考反向移植更改。
3. 如果需要，请添加最新动态或发布说明。有关指导，请参考贡献最新动态或发布说明。