Merge #410 improve contributing and index docs

modules/ROOT/pages/contribute-to-quick-docs.adoc

@@ -1,26 +1,12 @@
 = Contribute to Quick Docs
 
-This repository represents
+The goal:
-https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[asciidoc]
+move away from exposing users to the wild territory of wikis 
-documents roughly (semi-automatically) converted from the top 50
+(where helpful guides are mixed with draft documentation, user pages, rough notes, and so on)
-document-like pages in the Fedora Wiki. We want to move away from exposing
+to a nice, topic-oriented format
-users to the wild territory of workspace wikis and to a nice, topic-oriented
+with a pull-request-based workflow.
-format with a PR-based workflow.
+We appeciate your help!
 
-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
 
@@ -32,30 +18,64 @@ explain, you can create a new document from scratch.
 . 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.
 
+== 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 https://fedoraproject.org/wiki/Category:How_to[How To category]
+on the Fedora wiki. Many of those documents are ripe for conversion. (Many are also very out of date!)
+* https://ask.fedoraproject.org/c/english/97/l/latest?order=votes[Top-Voted] or https://ask.fedoraproject.org/c/english/97/l/top?order=views&period=yearly[highly-viewed] questions on Ask Fedora.
+* Frequent
+https://unix.stackexchange.com/questions/tagged/fedora?sort=frequent&pageSize=50[Fedora
+questions on Stack Exchange].
+* https://fedoramagazine.org[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
+Usually,
-potential for abuse is very high. We've developed a plugin for the Fedora
+wikis do not allow redirects to external sites,
-Wiki which allows redirects to _only_ pages on this site,
+because the potential for abuse is very high.
-https://docs.fedoraproject.org/. To create such a link, use the
+We've developed a plugin for the Fedora Wiki
-`#fedoradocs` macro by putting something like this at the top of the wiki
+which allows redirects to _only_ pages on this site,
-page you are obsoleting:
+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:
 
 [source,mediawiki]
 ----
-{{#fedoradocs: https://docs.fedoraproject.org/fedora-project/council/fpl.html}}
+{{#fedoradocs: https://docs.fedoraproject.org/en-US/council/fpl/}}
 ----
 
-Of course, you will want to replace that specific URL with the one for your
+Of course,
-new target page. The URL can't be something arbitrary — it must begin with
+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
+Once the redirect is in place,
-whisked (well, redirected, with the code `301 Moved Permanently`) to the
+visitors to that wiki page will be
-docs site. If you need to edit such a page to correct the URL, or to remove
+instantly whisked
-the redirect completely, use a form like:
+(well, redirected, with the code `301 Moved Permanently`)
-https://fedoraproject.org/w/index.php?title=Project_Leader&action=edit
+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
+

modules/ROOT/pages/index.adoc

@@ -1,5 +1,9 @@
 = Fedora Quick Docs
 
-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.
+This is a collection of short HOWTO and FAQ-style documentation for Fedora users. **Use the navigation menu menu on the left** to find an area of interest, and under that, solutions to your specific problem.
 
-This documentation is community-made. Your contributions and improvements are welcome!
+This documentation is community-made. Your xref:contribute-to-quick-docs.adoc[contributions and improvements ]are welcome!
+
+If you can't find an answer here, you may also get help on https://ask.fedoraproject.org[Ask Fedora], our questions-and-answers forum.
+
+// Note: link to https://docs.fedoraproject.org/en-US/project/help/ when that document is updated.