mirror of
https://pagure.io/fedora-docs/quick-docs.git
synced 2024-11-28 14:56:35 +00:00
Update Quick Docs landing page
Edited the Quick Docs landing page to be more user oriented. I moved the existing instructions about how to contribute to its own page. Fixes: #265 Signed-off-by: Richard Gregory <richardgrecoson@gmail.com>
This commit is contained in:
Richard Gregory
pbokoc
parent
6a97345c63
commit
15f13e05b2
3 changed files with 65 additions and 58 deletions
|
|
@ -1,3 +1,5 @@
|
||||||
|
* xref:contribute-to-quick-docs.adoc[Contribute to Quick Docs]
|
||||||
|
|
||||||
* xref:howto-file-a-bug.adoc[How to file a bug]
|
* xref:howto-file-a-bug.adoc[How to file a bug]
|
||||||
|
|
||||||
* xref:getting-started-guide.adoc[Getting started with Fedora]
|
* xref:getting-started-guide.adoc[Getting started with Fedora]
|
||||||
|
|
|
||||||
61
modules/ROOT/pages/contribute-to-quick-docs.adoc
Normal file
61
modules/ROOT/pages/contribute-to-quick-docs.adoc
Normal file
|
|
@ -0,0 +1,61 @@
|
||||||
|
= 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.
|
||||||
|
|
@ -1,61 +1,5 @@
|
||||||
= Fedora Quick Docs
|
= Fedora Quick Docs
|
||||||
|
|
||||||
This repository represents
|
This is a collection of short HOWTO and FAQ style documentation for Fedora users. Use the menu on the left to find an area of interest, and under that solutions to your specific problem.
|
||||||
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!*
|
This documentation is community-made. Your contributions and improvements are welcome!
|
||||||
|
|
||||||
== 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.
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue