mirror of
https://pagure.io/fedora-docs/quick-docs.git
synced 2024-11-25 13:44:51 +00:00
62 lines
2.9 KiB
Text
62 lines
2.9 KiB
Text
|
= Contribute to Quick Docs
|
||
|
|
|
||
|
|
This repository represents
|
||
|
|
http://asciidoctor.org/docs/asciidoc-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.
|
||
|
|
|
||
|
|
== Steps
|
||
|
|
|
||
|
|
. 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 have *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:
|
||
|
|
|
||
|
|
[source,mediawiki]
|
||
|
|
----
|
||
|
|
{{#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.
|