From 15f13e05b2b753e5d1ce625905f9788d14389319 Mon Sep 17 00:00:00 2001 From: Richard Gregory Date: Oct 26 2020 21:19:22 +0000 Subject: 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 --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 648a816..49b1123 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -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:getting-started-guide.adoc[Getting started with Fedora] diff --git a/modules/ROOT/pages/contribute-to-quick-docs.adoc b/modules/ROOT/pages/contribute-to-quick-docs.adoc new file mode 100644 index 0000000..bc702a6 --- /dev/null +++ b/modules/ROOT/pages/contribute-to-quick-docs.adoc @@ -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. diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 7f9b37b..27735b3 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -1,61 +1,5 @@ = Fedora 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. +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. -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. +This documentation is community-made. Your contributions and improvements are welcome!