参与改进和扩展文档条目

Fedora 文档团队 Version F36 and newer Last review: 2023-05-01

此文档介绍如何使用发布系统来构建 Fedora 文档网站。为你展示如何编辑现有文档或创建全新的内容，并把它们发布到英文版和其他语言版本。

参与 Fedora 文档编辑有很多不同的方式。其中一些方式试图使贡献者，不需要掌握网络内容管理系统，和存储管理贡献内容的技术背景知识。工具已经为你把这些工作都办了。使贡献者只用专注于内容本身。

欢迎抱着检查的态度来阅读文档。当你发现文档中含有错误或者不准确的地方，请使用下面介绍的易用编辑工具来帮助改进页面。如果遇到问题，不要客气尽管联系文档团队。

需要安装到本机的工具，是为了那些需要更多编辑功能的作者准备的。这些工具使编辑大型复杂且相互关联的文本集合时更高效。目标群体是已经有些经验的作者。

运作方式

Fedora 文档使用 Antora 来构建和管理网站。文档的内容相对固定，偶尔会更新。 Antora 工具的特性与此需求正吻合。它把静态文档集中到一起来生成完整的网站，包括导航栏、链接、文本格式化、位置安排、适配不同的显示设备等。有关更多 Antora 发布系统的信息，请参阅 Antora 网站 和 Antora 文档.

作为作者，你只需专注于内容本身，只管写。

正常流程

Fedora 文档采用 4-eyes(四眼) 原则。贡献后的内容要通过另一位作者的审阅。当你完善文本后，系统会创建一个 "Pull Request"(提交请求) 或 "Merge Request"(合并请求)，以便把你贡献的文本整合到文档正文。该请求会自动推送给其他作者， 董事会成员或与该文档内容相关的负责成员，进行审阅，审阅后或采纳并入或必要时发起一个讨论。通常一个请求需要 2 至 3 天的时间得到回复。

相关技术背景

Fedora 使用 AsciiDoc 这个简单高效的方案来格式化文本。它紧随日常笔记中自然的写作风格进行结构化和突出。通过这种方法，你可以使用任何编辑器，包括几乎所有能编辑和保存 AsciiDoc 文本的文字处理工具。下面会详细介绍。

AsciiDoc 文档存储在一系列 Git 仓库中。这是一个在软件编程领域十分流行的系统，也是非常适合文档管理的系统。Git "Pull拉取 (或 Merge合并) 请求的工作流程" 鼓励并简化了 4-eyes 四眼原则的应用。工作流的细节，只有在你想搭建本地工作环境来进行更专业和频繁的操作时才需要。若只使用其他的工具的话，工具会在后台自动完成这些步骤。

准备条件

为 Fedora Docs 贡献文档只需以下准备条件：

工具

Quick way: 'Edit' button

  • Make changes to a single file for minor fixes directly from web UI of Git forge.

  • Write access to upstream repo required.

  • Use it as an exception (without review process), rather than a recommended option.

Easy way: Web IDE of Git forge

  • Make changes to multiple files directly from web UI of Git forge.

  • No need to install anything in local computer or run Git commands in terminal.

  • Pull Requests for review process (Merge Requests in GitLab)

  • You do not need special permissions or write access to the original project.

Flexible and advanced way: Create a local writing environment

  • Work with multiple files and repos offline at your pace using your choice of text editor and terminal.

  • You can build and render the pages locally to test your changes using Podman container.

Typical ways to contribute

One can distinguish several typical types of contribution to Fedora documentation, for which the available tools are suitable in different ways.

There are many ways for various types of contribution. For example, typo fixes, adding short information or a link, update an article, write a new article.

Update an existing documentation page

This task involves minor changes. For example, typo fixes, adding short information or a link, or a correction to the text. This type is especially necessary whenever the documentation needs to be updated for a new software version.

The File Edit button are convenient for this purpose.

Extend an existing documentation domain

This task involves adding one or more new chapter(s) or section(s) with several chapters. For example, adding another container technique to the documentation of containerization.

The Web IDE is a convenient tool for this purpose. A local writing environment is useable as well, but may involve too much overhead if you want to contribute to just one document.

It is highly recommended to present the plan on one of the Docs communication channels before starting. You may get suggestions and tips on content, but also on editing. For example, file structure and naming conventions.

Introduce a new documentation area

This task involves a new extensive subject area, such as new software or a new administration tool. For example, inclusion of several sections and chapters and the creation of a new, separate repository.

For this type, setting up a local writing environment is useful and worthwhile.

In any case, a prior discussion with the Docs team is necessary, if only to create the technical prerequisites.

Want to help? Learn how to contribute to Fedora Docs ›