为快速文档做贡献

The Fedora Docs Team. Version all versions Last review: 2023-08-25
我们的目标是从 wiki 页面(其中有用的指南与草稿文档、内部注释混合在一起)转向一个漂亮的、面向主题的操作指南和具有基于拉取请求的工作流程的代码打包教程。感谢您的帮助!

步骤

  1. Pick a document to update. You can find documents needing updates in the modules/ROOT/nav.adoc file. They are on the commented-out lines (those that start with a //FIXME).

  2. Fork the https://pagure.io/fedora-docs/quick-docs repo.

  3. Make your changes to the .adoc file you want to improve.

  4. Uncomment the file in nav.adoc remove the FIXME from the xref..

  5. Build a local preview to ensure your changes look the way you intended: Make sure you either have Podman or Docker installed, On a Linux desktop run ./docsbuilder.sh. On macOS run either ./docsbuilder.sh -p or ./preview.sh. Follow instructions printed on the command line.

  6. When you are satisfied with your updates, submit a pull request with your improvements.

  7. If migrating a wiki page, create a redirect on the old page — see below.

Possible Source Material

Perhaps you just want to improve an existing document, in which case the above is all you need. Or maybe you already have something in mind. But if you are interested in helping but don’t know where to start, here are some places to look for ideas:

  • The old How To category on the Fedora wiki. Many of those documents are ripe for conversion. (Many are also very out of date!)

  • Common Issues questions on Ask Fedora.

  • Frequent Fedora questions on Stack Exchange.

  • Fedora Magazine articles. The magazine format is conversational, and understood to represent a moment in time. Quick Docs versions should be more to-the-point, and kept updated if commands or best pratices change.

Wiki Redirects

Usually, wikis do not allow redirects to external sites, because the potential for abuse is very high. We’ve developed a plugin for the Fedora Wiki which allows redirects to only pages on this site, https://docs.fedoraproject.org/. To create such a link, use the #fedoradocs macro by putting something like this at the top of the wiki page you are replacing:

{{#fedoradocs: https://docs.fedoraproject.org/en-US/council/fpl/}}

Of course, you should to replace that example URL with the one for your new target page. Again, the URL can’t be something arbitrary it must begin with https://docs.fedoraproject.org/.

Once the redirect is in place, visitors to that wiki page will be instantly whisked (well, redirected, with the code 301 Moved Permanently) to the docs site.

Note that there is no validation that the target exists or is correct — please double-check that any redirects you create work properly before moving on.

If you need to edit such a page to correct the URL, or to remove the redirect for some reason, construct a wiki site URL with &action=edit, like:

https://fedoraproject.org/w/index.php?title=Project_Leader&action=edit