Contribute to Quick Docs
This repository represents https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[asciidoc] documents roughly (semi-automatically) converted from the top 50 document-like pages in the Fedora Wiki. We want to move away from exposing users to the wild territory of workspace wikis and to a nice, topic-oriented format with a PR-based workflow.
So, this is kind of a seed project. *Your help wanted!*
Other Source Material
There is a https://fedoraproject.org/wiki/Category:How_to[How To category] on the wiki. Many of those documents are ripe for conversion. https://ask.fedoraproject.org/top/all[Popular questions on Ask Fedora] are also likely to be useful starting points — or, also, frequent https://unix.stackexchange.com/questions/tagged/fedora?sort=frequent&pageSize=50[Fedora questions on Stack Exchange].
Or, of course, if there's something you care about which you can help explain, you can create a new document from scratch.
Pick a document to update. You can find documents needing updates in the [filename]`modules/ROOT/nav.adoc` file. They are on the commented-out lines (those that start with a `//FIXME`).
Fork the https://pagure.io/fedora-docs/quick-docs repo.
Make your changes to the `.adoc` file you want to improve.
Uncomment the file in [filename]`nav.adoc` remove the `FIXME` from the xref..
Build a local preview to ensure your changes look the way you intended: Make sure you either have *Podman* or *Docker* installed, and run `./build.sh && ./preview.sh`. Follow instructions printed on the command line.
When you are satisfied with your updates, submit a pull request with your improvements.
If migrating a wiki page, create a redirect on the old page — see below.
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 obsoleting:
{{#fedoradocs: https://docs.fedoraproject.org/fedora-project/council/fpl.html}}
Of course, you will want to replace that specific URL with the one for your new target page. 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. If you need to edit such a page to correct the URL, or to remove the redirect completely, use a form like: https://fedoraproject.org/w/index.php?title=Project_Leader&action=edit
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.