文档 Writer's Toolkit 贡献

贡献文档

有多种不同的方式可以为 Grafana Labs 的文档做出贡献。选择最适合您的方式，了解如何与文档团队互动，并通过贡献您的想法提供帮助。

发送电子邮件至 docs@grafana.com

当您想对某个主题提出建议或提供反馈，但不想亲自进行更改时，可以报告问题。

报告问题让您可以自由地表达您的想法，而无需确定具体的措辞。您的建议可以是对措辞的小幅修改，也可以是更大、更实质性的改动。

您可以通过点击每个文档页面底部的“发送电子邮件至 docs@grafana.com”链接来通过电子邮件报告问题。或者您也可以直接发送电子邮件至 docs@grafana.com

1. 在邮件正文中提供您的反馈。
2. 包含当前页面的链接。
3. 发送您的电子邮件。

Grafana Labs 文档团队会定期检查收件箱并及时回复电子邮件。

在 GitHub 中提出编辑建议

如果您想推荐一个小的更改，例如建议更正某个主题，您可以直接在 GitHub 中编辑该主题。

小的更改可能包括

• 为任务添加步骤
• 为概念添加解释性语言
• 提供示例

开始之前

• 创建一个 GitHub 账户。
• 查找源仓库。要查找源仓库，请参阅查找源仓库。

查找源仓库

从公共项目发布的文档的“最新”（latest）和“下一个”（next）版本都有一个带有铅笔图标的“在 GitHub 中提出编辑建议”链接。点击此链接可直接在 GitHub 中编辑页面。

如果页面没有提出编辑建议链接，则表示文档不是开源的。只有 Grafana Labs 员工才能更新闭源文档。如果您不是 Grafana Labs 员工，仍然可以发送电子邮件。

例如，Grafana Cloud 文档位于网站仓库中。

一些 Grafana Cloud 内容从其他项目挂载。挂载列表位于网站仓库的 Hugo 配置文件中。

编辑页面

1. 在文档网站的页面上，点击在 GitHub 中提出编辑建议。

2. 进行您的更改。

3. 点击提议更改。

   GitHub 会创建一个拉取请求（pull request），然后该请求会经过审查和批准工作流程。

开发新主题

如果您想从头开始开发一个新主题，您可以创建一个文档计划，并与技术写作团队的成员协作。根据书籍 Docs for Developers，文档计划是用于预测写作过程走向的灵活大纲。

您的文档计划有助于您

• 识别信息空白，并解释如何填补这些空白。
• 在写作过程开始前从用户和利益相关者那里获取反馈。
• 考虑您可能采取的不同方法，并决定其中一种。

测试您的更改

最佳实践是让其他人测试您撰写的任何任务。如果另一个用户*仅*使用您撰写的步骤就能成功完成任务，而不是猜测或利用他们的固有知识，那么您的任务就通过了测试。然而，您很容易发现自己跳过了某些步骤，因为*您*对您正在解释的主题非常熟悉。

新用户或其他团队的成员对于这些测试非常有帮助。

审查您的更改

在将更改推送到 GitHub 之前，您可以查看文档的本地构建，以便审查您的工作。有关使用 Git 的更多信息，请参阅使用 Git。

要查看本地构建，请参阅测试文档更改

推送更改并创建拉取请求

当您准备好让其他人审查您的工作时，请执行以下任务

1. 添加您的更改，这为下一次提交准备您的内容。

2. 提交您的更改。

3. 将您的更改推送到 GitHub。

4. 在 GitHub 中创建拉取请求。

5. 在编写拉取请求的描述时，使用GitHub 关键词，例如“Fixes #1234”，将您的拉取请求链接到问题，并利用 GitHub 的自动化功能进行状态更新和关闭已解决的问题。

6. 添加 type/docs 标签，以便 Grafana Labs 文档团队可以追踪该问题。

   文档构建系统会自动执行一系列测试，以确保内容与文档仓库中的其他内容不冲突。

拉取请求审查和批准工作流程

当您向仓库添加拉取请求并分配 type/docs 标签时，它会被添加到由 Grafana Labs 文档团队成员定期审查的队列中。

Grafana Labs 文档团队力求及时审查所有 PR。

跨版本贡献

当您编辑项目的 main 分支时，会影响网站 next 目录中的内容。要编辑以前的版本或 latest（最新发布版），您必须将更改回移植到项目仓库中长期存在的版本分支中。

要回移植更改，请在 GitHub 拉取请求上使用 backport 标签。有关更多信息，请参阅回移植更改。

Grafana 机器人 Grot 会在合并提交可以无冲突地挑选（cherry-picked）时自动创建一个回移植拉取请求。如果此过程因合并冲突而失败，Grot 会发布一条评论，解释如何手动回移植更改。