项目文档

本节将帮助您为 Ansible 项目添加文档或改进现有文档。GitHub 上的入门project-template提供了开始文档工作的脚手架文件。从模板构建的网站可在ReadTheDocs上获得。

创建新的文档项目

开始新的文档工作的 Ansible 项目应遵循以下指南

Markdown 简单、无处不在，并且大多数贡献者都很熟悉。出于这些原因，Ansible 社区团队建议使用 Markdown 作为文档格式。
mkdocs是建议用于从 Markdown 构建文档的工具。
ReadtheDocs是建议发布 Ansible 项目文档的位置。
可使用Ansible 风格指南来帮助确保您的项目编写良好并遵循技术文档指南。

如果您不使用 GitHub project-template，请按照以下步骤设置文档

在您的项目存储库中创建一个/docs目录。
遵循 project-template 中提出的文档结构，以确保包含所有项目通用的重要指南。
将mkdocs.yml添加到项目根目录，并修改nav部分以匹配您提出的导航/指南集。
在项目根目录中创建.readthedocs.yaml。
与Ansible 社区团队协调，以设置自动发布并让您的文档添加到 Ansible 生态系统页面。

创建文档的基础知识

Diataxis包含一组关于如何编写不同类型文档的良好指南。接下来的部分将总结这些信息，以便快速参考。

教程/入门指南

我们倾向于将这些称为入门指南。它们是为新用户（或开发人员）提供快速介绍，帮助他们完成某些操作。重点在于实践。 Ansible 入门指南就是一个很好的例子。教程应使用编号步骤（流程）。我们将在操作指南部分介绍流程。

解释/概念

解释或概念描述“是什么以及为什么”。

请参阅 Red Hat 的概念解释以获取更多详细信息，但请记住它使用的是 asciidoc，而不是 markdown。

操作指南/流程

操作指南是大多数读者使用的指南。

它们应该专注于所谓的“用户故事”。用户故事帮助您将开发/产品功能转换为用户或开发人员想要实现的目标。

作为<用户类型>，我想要<某个目标>，以便<某个原因>

例如，本指南满足以下用户故事

作为项目开发人员，我希望确保我的项目符合 Ansible 项目建议 以便我可以确保顺利集成到 Ansible 生态系统中

您应该将这些流程编写为一系列步骤，并带有引言句。

观看您最喜欢的运动队比赛

搜索哪些电视或流媒体服务播放比赛。
订阅该服务。
设置日历提醒，以免忘记比赛。

请参阅 Red Hat 的流程解释以获取更多详细信息，但请记住它使用的是 asciidoc，而不是 markdown。

参考

参考是事实——列表、表格等。您的读者可以参考这些内容来帮助他们了解诸如可用哪些参数或选项等内容。Ansible 模块是参考材料的一个示例。

请参阅 Red Hat 的参考解释以获取更多详细信息，但请记住它使用的是 asciidoc，而不是 markdown。

Ansible 项目中包含的指南类型

注意如果项目只需要一页，那么指南可能只有一页。

您的项目可能需要以下类型的文档

许可证信息。
社区指南：包括行为准则参考和沟通指南。
用户指南：包括入门、安装、配置指南和 CLI 参考。
贡献者指南：描述项目在 Ansible 生态系统中的位置，提供有关非代码和代码贡献（包括文档和测试）的指南。
维护者指南：涵盖如何成为维护者及其职责、治理、发布以及特定于项目的其他维护者任务。

文档站点模板由project_template 存储库提供，其中包含所有上述指南的模板，以及解释和建议。

下面还有一些关于某些指南的其他建议。

安装指南

这是安装项目的方法。它应该以流程为中心，并包括

安装
卸载
升级

您的安装指南可能需要参考“参考”部分中的配置页面以进行初始设置。

如果您的项目支持，请考虑为多个操作系统/环境包含流程。

入门

本指南充当读者的教程。它应该涵盖读者可以遵循的简单场景，以完成他们的第一个“操作”。这是项目的“Hello World”。

请参阅Ansible 入门以获取一个很好的示例。

参考

您的文档应包含以下参考部分

配置这涵盖了任何必需的配置文件。请参阅Ansible 配置以获取示例。考虑一下您的项目是否可以从代码中自动生成配置，作为保持文档和代码同步的最佳方式。

CLI 参考如果您的项目包含 CLI，则此参考部分应详细说明比手册页提供的更多内容。如果可能，命令参考应从代码中自动生成。

移植指南/变更日志所有项目都应包含变更日志和移植指南，以帮助用户在升级到项目的新版本时获得帮助。请参阅Ansible 集合变更日志指南以了解如何执行此操作的良好示例。

路线图您应该考虑拥有一个项目路线图，以便您的项目贡献者和用户可以了解未来版本中将包含的内容。

用户指南

在这里，您需要考虑的不仅仅是项目提供的功能，还有它解决的问题。这些是您的“操作指南”页面。再次考虑那些用户故事

作为<用户类型>，我想要<某个目标>，以便<某个原因>

将所有功能都视为飞机驾驶舱中的元素。您的参考材料将描述每个按钮、开关和显示面板。

用户指南的作用是告诉用户如何驾驶飞机

起飞
着陆
启用自动驾驶仪以便进行舒适的越洋飞行

好的用户指南还有什么？验证或故障排除帮助。如果您正在着陆飞机并且起落架无法放下该怎么办？

因此，一个通用的用户故事/用例将包含以下主题

此用例是什么，为什么读者想要使用它？
一个分步指导读者应用此用例的编号流程。
故障排除/验证最终结果（如果适用）。

注意 - 用户故事/用例不应列出读者可能使用的所有选项。这些详细信息应在参考部分或后续流程中提供。

贡献者指南

由于这些是开源项目，因此您希望让潜在的贡献者轻松参与您的项目。请记住，贡献者可以超越代码贡献。

您的贡献者指南应包含： - 对Ansible 行为准则的引用。 - 您使用的沟通渠道（矩阵、论坛标签） - 如何设置他们的开发环境 - 您的问题/PR 在哪里跟踪，等等。