A (too) extensive update, so that the page would be publishable in principle now

modules/ROOT/nav.adoc

@@ -11,18 +11,23 @@
 * Where to find
 
 * xref:contributing-docs/index.adoc[Write contributions to Docs]
-** Tool Guides
+
+** Contributing to existing documentation 
+// xref:contributing-docs/contrib-existing-documentation.adoc[Contributing to existing documentation]
+** xref:contributing-docs/contrib-release-notes.adoc[Contributing to Release Notes]
+** xref:contributing-docs/contrib-new-documentation.adoc[Contributing a new documentation site]
+
+** Contribution Tools
 *** xref:contributing-docs/tools-7step-gitlab-howto.adoc[7 Step HowTo for casual contributions (for GitLab-based pages)]
 // ** xref:contributing-docs/7step-pagure-howto.adoc[7 Step HowTo for casual contributions (for Pagure-based pages)]
 *** HowTo for casual contributions (for Pagure-based pages)
 //** xref:contributing-docs/use-web-ide-ui.adoc[How to profoundly use the Gitlab web IDE (permanent members)]
 *** How to profoundly use the Gitlab web IDE (permanent members)
 //** xref:contributing-docs/use-file-edit-if.adoc[How to profoundly use Pagure (permanent members)]
-//** xref:contributing-docs/use-local-work-env.adoc[How to create and use a local work environment]
-*** How to create and use a local work environment
-//**** xref:contributing-docs/use-local-work-preview.adoc[Building a Local Preview]
-//**** xref:contributing-docs/use-local-work-git.adoc[Git for docs writers]
-//** xref:contributing-docs/contrib-new-documentation.adoc[Create and publish new documentation sites]
+*** xref:contributing-docs/tools-localenv-an-introduction.adoc[How to create and use a local Fedora authoring environment]
+**** xref:contributing-docs/tools-localenv-setting-up.adoc[Setting up a local Fedora authoring environment]
+**** xref:contributing-docs/tools-localenv-preview.adoc[Building a Local Preview]
+**** xref:contributing-docs/tools-localenv-git-guide.adoc[Git for docs writers]
 
 ** xref:contributing-docs/style-guide.adoc[The docs style guide]
 ** xref:contributing-docs/asciidoc-intro.adoc[AsciiDoc for Fedora]
@@ -30,12 +35,12 @@
 *** xref:contributing-docs/asciidoc-reusable-attributes.adoc[Reusable attributes]
 // ** xref:contributing-docs/translations.adoc[Working with Translations]
 ** Working with Translations
-** xref:contributing-docs/special-contributing-to-release-notes.adoc[Special case Contribute to Release Notes]
 
-// * xref:infrastructure/index.adoc[Keep Docs up and running]
-* Keep Docs up and running
-//* xref:contributing/design-ux-contribution.adoc[Design the user interface for Docs]
-//** Design the user interface for Docs
+
+//* Contribute to keeping Docs up and running
+* xref:contributing-infra/index.adoc[Contribute to keeping docs up and running]
+** xref:contributing-infra/design-ux-contribution.adoc[Design the user interface for Docs]
+
 
 //* xref:archive/index.adoc[What we have achieved so far]
 * What we have achieved so far

modules/ROOT/pages/contributing-docs/asciidoc-intro.adoc

@@ -1,4 +1,6 @@
 = AsciiDoc for Fedora Documentation Writers
+Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
+v0.0.1, 2022-09-26
 
 This documentation section provides advice, tips, and resources for the Fedora Community writing AsciiDoc for Fedora documentation.
 The purpose of this section is not to duplicate what already exists, but to point you the right way.

modules/ROOT/pages/contributing-docs/asciidoc-markup.adoc

@@ -1,7 +1,7 @@
 = AsciiDoc markup
 Fedora Documentation Team <dhttps://discussion.fedoraproject.org/tag/docs>
 v0.0.1, 2020-08-26
-:toc:
+
 
 This page shares general information about writing in AsciiDoc as well as Fedora/Antora-specific syntax that comes up often in Fedora Documentation.
 

modules/ROOT/pages/contributing-docs/asciidoc-reusable-attributes.adoc

@@ -1,7 +1,7 @@
 = Reusable attributes
 Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
 v0.0.1, 2020-08-26
-:toc:
+// :toc:
 
 This page explains how to use reusable metadata, or attributes, across multiple AsciiDoc documents in Fedora Documentation.
 

modules/ROOT/pages/contributing-docs/contrib-existing-documentation.adoc

@@ -0,0 +1,95 @@
+= Contributing to existing documentation
+
+This section describes how to contribute to existing documentation - that is, documentation that already has been published on the website.
+Before you start following this procedure, make sure that you fulfill all the requirements listed in xref:index.adoc[Prerequisites].
+
+[TIP]
+If you are interested in contributing to Release Notes, see the xref:contributing-docs/contrib-release-notes.adoc[appropriate page].
+
+Each Fedora Docs page includes an "Edit this Page" link at the top.
+For simple updates, changes can be submitted directly from the Pagure web interface.
+For larger or more complex edits, you should prepare and test your changes offline before submitting.
+
+== Editing online in Pagure
+
+. Click the "Edit this Page" link to load the documentation source.
+  You will be taken to the appropriate content repository in Pagure.
+
+. Above the source listing on the right side, click "Fork and Edit".
+  (If you have already forked the repository, this button will be labeled "Edit in your fork" and you can skip to the next step.)
+
+.. If you are not already logged in to Pagure, you will be asked for your credentials.
+
+.. Wait for the operation to finish.
+   You may need to refresh the page as it does not always update automatically when the process is done.
+
+. Once the file is loaded in your fork, make any changes necessary to the content, commit them to your fork, and prepare a pull request (PR).
+
+.. Each PR should be submitted from its own branch in your repository.
+   Under the "Branch" heading of the commit interface, select "New branch" and give the branch a short, unique name.
+
+.. Fill out the commit message form.
+
+.. Click "Commit changes" to create the branch and save these changes to your fork.
+
+. Once the commit is saved, the page will refresh to a list of Commits for your fork.
+
+. To include additional, related changes, repeat this process and commit them to the same branch.
+
+. When you are ready, click "Create pull request" and fill out the PR form to submit your branch to the upstream repository.
+
+[TIP]
+.Git commit tips
+====
+* When naming your branch, use only ASCII letters, digits, hyphens (`-`) and underscores (`_`).
+  The name pass:q[_may_] contain, but not start or end with, single periods (`.`).
+Spaces, double periods (`..`), and most other punctuation are not permitted.
+
+* The commit title is how your edit will be identified in the repository log for the page.
+  The suggested title, "Update [filename]``pathname``", is sufficient for small edits.
+  For some advice on writing good commit messages,
+see link:++https://commit.style++[commit.style] by Tim Pope (author of [application]`vim`).
+
+* Use the "Commit Description" field to provide additional detail if necessary, but keep it short.
+  You will have the opportunity to explain or discuss your changes when you submit your PR.
+====
+
+== Offline editing
+
+. Click the "Edit this Page" link to load the documentation source.
+  You will be taken to the appropriate content repository in Pagure.
+  Once you have located the correct repository, make a fork if you do not have it forked already:
+
+.. In the top right corner, click Fork.
+
+.. If you are not already logged in to Pagure, you will be asked for your credentials.
+
+.. Wait for the operation to finish.
+  You may need to refresh the page as it does not always update automatically when the process is done.
+
+.. Clone your fork.
+
+. Check out a new branch, and add your contributions.
+
+. If you added any new files, then ensure they are included in a reasonable spot in the repository's [filename]`nav.adoc` configuration file
+
+. Build locally and make sure everything looks the way you expect.
+  See xref:contributing-docs/tools-localenv-preview.adoc[Building a local preview] for instructions.
+
+. Once you finish, commit your changes and push them to your fork.
+
+. Use Pagure to make a pull request from your fork to the main repository's master branch.
+
+== Managing your pull request
+
+Someone will see your pull request and either merge it, or provide feedback if there is something you should change.
+Work with the people commenting to make sure your contributions are up to standards.
+
+[NOTE]
+====
+If nobody reacts to your pull request in several days, try bringing it up on one of the link:++https://calendar.fedoraproject.org//docs/++[weekly meetings], the Matrix channel (https://matrix.to/#/#docs:fedoraproject.org[#docs] on Fedora Chat), or the link:++https://discussion.fedoraproject.org/tag/docs++[mailing list].
+====
+
+Your changes will appear online sometime after the pull request is merged.
+The site is being updated daily.
+If your changes do not appear online within 60 hours of your PR being merged, ping `asamalik` (Adam Šamalík) on the IRC channel and ask him about it.

modules/ROOT/pages/contributing-docs/contrib-new-documentation.adoc

@@ -1,6 +1,6 @@
 include::ROOT:partial$attributes.adoc[]
 
-= Create and publish new documentation sites
+= Contributing a new documentation sites
 
 [abstract]
 ____
@@ -8,10 +8,10 @@ This section describes how to add a complete new piece of documentation that cov
 ____
 [NOTE]
 ====
-The following text is not yet edited and needs to be adjusted. 
+The following text is slightly outdated, does not take into account the GitLab repositories and still needs to be adjusted. 
 ====
 This section describes how to create and publish new documentation to the docs.fedoraproject.org website.
-Before you start following this procedure, review all the requirements listed in xref:prerequisites.adoc[Prerequisites].
+Before you start following this procedure, review all the requirements listed in xref:contributing-docs/index.adoc#prerequisites[Prerequisites].
 
 [IMPORTANT]
 ====

modules/ROOT/pages/contributing-docs/contrib-release-notes.adoc

@@ -1,6 +1,8 @@
 include::ROOT:partial$attributes.adoc[]
 
 = Contributing to Release Notes
+Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
+v0.0.1, 2022-09-26
 
 This section describes how to contribute to Fedora Release Notes.
 Before you start following this procedure, make sure that you fulfill all the requirements listed in xref:./index.adoc#Prerequisites[Prerequisites].

modules/ROOT/pages/contributing-docs/index.adoc

@@ -1,4 +1,6 @@
 = Write contributions to Docs
+Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
+v0.0.1, 2022-09-26
 
 [abstract]
 ____
@@ -27,6 +29,7 @@ Fedora uses _AsciiDoc_ to format text in a simple and efficient way, that anyone
 
 The AsciiDoc text document is stored in series of GIT repositories. The is system especially popular among software developers, but also very capable for managing text documents. GIT encourages and facilitates the use of the 4-eyes principle by a "Pull (or Merge) Request Workflow". You only need to worry about the details of this workflow if you want to set up a local work environment intended for professional and frequent contributions. All other tools take care of the necessary steps in the background. 
 
+
 == Prerequisites
 
 The only requirements for contributing documentation to Fedora Docs are:
@@ -36,7 +39,7 @@ The only requirements for contributing documentation to Fedora Docs are:
 * Basic knowledge of *AsciiDoc* markup language (see xref:contributing-docs/asciidoc-markup.adoc[AsciiDoc for Fedora])
 
 
-== The Tools
+== The tools
 
 The quick way – Editing a specific file::
    Edit a specific file you with to improve.

modules/ROOT/pages/contributing-docs/style-guide.adoc

@@ -1,8 +1,10 @@
 = Fedora Documentation Style Guide
+Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
+v0.0.1, 2022-09-26
 
 [NOTE]
 ====
-Editors note: First draft to be discussed. Please do not quote publicly and do not link publicly.
+Editors note: This is not yet the final version. Changes can still be introduced in the ongoing discussion.
 ====
 
 

modules/ROOT/pages/contributing-docs/tools-7step-gitlab-howto.adoc

@@ -1,4 +1,6 @@
-= Fedora Docs "HowTo" for casual contributions
+= Fedora Docs "HowTo" for casual contributionsFedora 
+Documentation Team <https://discussion.fedoraproject.org/tag/docs>
+v0.0.1, 2022-09-26
 
 == 7 clicks to create and propose a change in a Docs page
 

modules/ROOT/pages/contributing-docs/tools-file-edit-pagure.adoc

@@ -4,7 +4,7 @@ This section describes how to contribute to existing documentation - that is, do
 Before you start following this procedure, make sure that you fulfill all the requirements listed in xref:index.adoc[Prerequisites].
 
 [TIP]
-If you are interested in contributing to Release Notes, see the xref:contributing-docs/special-contributing-to-release-notes.adoc[appropriate page].
+If you are interested in contributing to Release Notes, see the xref:contributing-docs/contrib-release-notes.adoc[appropriate page].
 
 Each Fedora Docs page includes an "Edit this Page" link at the top.
 For simple updates, changes can be submitted directly from the Pagure web interface.

modules/ROOT/pages/contributing-docs/tools-localenv-an-introduction.adoc

@@ -0,0 +1,131 @@
+= How to create and use a local Fedora authoring environment
+Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
+v0.0.1, 2022-09-26
+
+[abstract]
+____
+In a local work environment you work offline, without a mandatory permanent internet connection, using a local git repository containing a complete set of documents for a specific documentation, and local tools to edit and preview those. It is by far the most flexible way of working and allows extensive adaptation to individual work routines and work equipment. 
+____
+
+A local writing environmant allows full access to all the resources you routinely use on your workstation, and is therefore perfectly adaptable to your style of working. It is particularly suitable for the creation of a complete new documentation on a topic or for a very extensive revision of an existing documentation.
+
+== Prerequisites 
+
+1. Basically you need to fullfill the basic requirements as specified in xref:contributing-docs/index.adoc#prerequisites[Write contributions to Docs]
+2. You need to install various tools, specifically git and a container providing the instrumentation to convert the AsciiDoc files and a minimal web server to display them. This is described in xref:contributing-docs/tools-localenv-setting-up.adoc[Setting up a local working environment].
+3. The system uses CLI tools in large parts. A certain experience in handling terminal windows is therefore necessary or must be learned in parallel.
+
+
+
+== How to work in a local Fedora authoring environment
+
+This parapgraph provides a short, step-by-step guide. For greater details lppk at xref:contributing-docs/
+
+=== Preparations
+
+If you want to start working on a Dockumentation you haven't worked on before, follow the steps to set up a local authoring environment. Otherwise
+
+1. Change to the base directory of your documentation project.
++
+[source,]
+----
+[…]$ cd ~/<my-doc-project>
+----
+2. Update your local data 
++
+[source,]
+----
+[…]$ git pull
+----
+
+=== Work on content
+
+1. List the branches and check, if you are on the branch to intend to work on
++
+[source,]
+----
+[…]$ git branch
+* main
+stg
+----
++
+Usually you see a main branch (sometimes named master) and one or more project specific branches. Many projects have a staging (stg) branch among others to facilitate a preview for a broader audience. A '*' marks the currently active branch
++
+Switch to the branch as necessary
++
+[source,]
+----
+[…]$ git git checkout <your_branch>
+----
+2. Use the editor of your choice to modifiy content. Keep your default directory as is and load the necessary file(s) in the editor.
+
+3. Update preview and check:
++
+[source,]
+----
+[…]$ ./build.sh && ./preview.sh
+----
+Preview in your browser using the address localhost:8080 
+
+4. Repeat step 2 & 3 as required. 
+
+=== Save your work
+
+1. Check git status
++
+[source,]
+----
+[…]$ git status
+On branch stg
+Your branch is up to date with 'upstream/stg'.
+
+Changes to be committed:
+  (use "git restore --staged <file>..." to unstage)
+	modified:   modules/ROOT/nav.adoc
+	modified:   modules/ROOT/pages/contributing-docs/asciidoc-intro.adoc
+
+Changes not staged for commit:
+  (use "git add/rm <file>..." to update what will be committed)
+  (use "git restore <file>..." to discard changes in working directory)
+	modified:   modules/ROOT/pages/contributing-docs/asciidoc-markup.adoc
+	modified:   modules/ROOT/pages/...
+	modified:   modules/ROOT/pages/...
+
+Untracked files:
+  (use "git add <file>..." to include in what will be committed)
+	modules/ROOT/pages/contributing-docs/contrib-new-documentation.adoc
+	modules/ROOT/pages/...
+	modules/ROOT/pages/...
+----
++
+You get a list of files ready to be committed, of modified files, and maybe of untagged files.
+
+2. As advised in the output, use _git add_ to add one by on to the ready to be committed files. Or use _git add -v_ to add all in one go. Please note that it is best to create small commits that combine related files for a problem domain. 
++
+[source,]
+----
+[…]$ git status add modules/ROOT/pages/contributing-docs/asciidoc-markup.adoc
+[…]$ git status add modules/ROOT/pages/...
+[…]$ git status add modules/ROOT/pages/...
+----
+
+3. Commit your work locally. Please choose a commit comment that is as short as possible, but also meaningful to third parties. 
++
+[source,]
+----
+[…]$ git commit -m „<YOUR COMMIT MESSAGE>“
+----
+
+4. Transfer to your work to your fork of the repository. If you don't specify a branch, git takes the current one.
++
+[source,]
+----
+[…]$ git push origin [<branch>]
+----
+
+5. In your browser open the repository and switch to your fork. Create a pull request.
+
+6. __Done__. Repeat steps 2 - 4 as needed.
+
+
+

modules/ROOT/pages/contributing-docs/tools-localenv-equipment.adoc

@@ -1,12 +0,0 @@
-= How to create and use a local work environment
-
-TBD
-
-
-
-
-For larger updates or to contribute all-new documentation, you may also need:
-
-* A plaintext editor such as [application]`vim`, [application]`emacs`, [application]`Atom`, [application]`VSCode`, etc., preferably with AsciiDoc syntax highlighting.
-* [application]`git` (see xref:contributing-docs/tools-localenv-git-guide.adoc[Git for docs writers])
-* [application]`Podman` if you use a Linux OS such as Fedora or [application]`Docker CE` if you use macOS.

modules/ROOT/pages/contributing-docs/tools-localenv-git-guide.adoc

@@ -1,4 +1,6 @@
 = Git for docs writers
+Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
+v0.0.1, 2022-09-26
 
 Some would-be documentation contributors may not know how to effectively use Git to contribute to Fedora documentation.
 This document attempts to provide some guidance.

modules/ROOT/pages/contributing-docs/tools-localenv-preview.adoc

@@ -1,6 +1,8 @@
-:experimental:
 
 = Building a local preview
+Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
+v0.0.1, 2022-09-26
+
 Because the documentation site is using a markup language instead of a WYSIWYG editor, the sources do not look exactly like the rendered page will. Therefore it is necessary to check that your changes look the way you want them to before you push and make a pull request. This involves building a local preview.
 
 There are two shell scripts available in each existing repository (including the template repository used to create new content): `build.sh` and `preview.sh`. 

modules/ROOT/pages/contributing-docs/tools-localenv-setting-up.adoc

@@ -0,0 +1,54 @@
+= Setting up a local Fedora authoring environment
+Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
+v0.0.1, 2022-09-26
+
+[abstract]
+____
+This guide describes step by step the setup of a local Fedora authoring environment. Workstations with Linux and macOS are directly supported. A graphical user interface is helpful, but not an requirement. 
+____
+
+== How it works
+
+The Fedora publishing system uses plain text files with AsciiDoc formatting for all content. Therefore, you need a text editor to work on it.
+
+Fedora uses git repositories for file storage and version control. Therefore, git must be installed on the workstation. Editing is then done in the git working directory. 
+
+In the course of work, one would like to check the formatting and appearance. This requires a minimal display system.  Every Fedora docs repository provides this, but it requires a Docker or Podman container.  
+
+== Prerequisites 
+
+=== Plain text editor
+
+Basically, you can use any plain text editor you are used to, among others [application]`vim`, [application]`emacs`, [application]`Atom`, [application]`VSCode`, etc.
+
+Very helpful is AsciiDoc syntax highlighting and also already a rough preview of the formatted text. Here the [application]`Atom` program editor and the special AsciiDoc editor [application]`AsciiDocFX` stand out. Both provide an optional split screen containing a rough preview. [application]`AsciiDocFX` provides additionally a editing menue as it is known by text processing software.
+
+Both are FOSS projects and make the software freely available. The https://atom.io/[Atom project] provides the editor for Linux, macOS and Windows. The https://asciidocfx.com/[AsciiDocFX project] provides a Java binary as Linux, macOS or Windows installation file that furthermore works on any operating system with a Jave runtime environment. 
+
+=== Git
+
+The git version control system is available for virtually all operating systems. On a Fedora workstation it is installed via dnf. We use the command line only tool here. 
+
+[source,]
+----
+[…]$ sudo dnf install git
+----
+
+For other operating systems, use the appropriate installation files.
+
+=== Container
+
+The preview system requires a container. The container is set up automatically, but a container runtime environment must be available and active. 
+
+On a Fedora system, simply install Podman from the Fedora repository.
+[source,]
+----
+[…]$ sudo dnf install podman
+----
+
+On macOS or Windows, install Docker CE of the https://www.docker.com/[Docker project]. 
+
+== Setting up a documentation project
+
+Comming soon
+

modules/ROOT/pages/contributing-infra/design-ux-contribution.adoc

@@ -7,7 +7,7 @@ _____
 
 [NOTE]
 ====
-The following text is still unedited and needs adjustment.
+The following text needs more detailed and adjustment.
 ====
 
 This page explains how to contribute to the Fedora Docs Team as a designer or user interface (U.I.) / user experience (U.X.) developer.

modules/ROOT/pages/contributing-infra/index.adoc

@@ -0,0 +1,19 @@
+include::ROOT:partial$attributes.adoc[]
+
+= Contribute to keeping Docs up an running
+
+[abstract]
+____
+This document explains how to contribute to maintaining and improving the publishing system used to build the Fedora Documentation website.
+____
+
+Maintainig the Docs website is a lot of work needing skills in different areas.
+
+Graphical design::
+The graphical and functional appearance of Docs web pages require continuous adaptation to additional or changing needs. Members with expertise in web design, UI or UX development can help optimize these areas.  
+Git maintainers::
+All documentation is stored in GIT along with issues and organisational tasks. Community members with experience in managing GIT repositories can help maintain and update the Docs repositories. 
+Workflow maintenance::
+The processes for creating the web pages are automated. Members with experience in CI can contribute to maintain and improve these processes. 
+
+The relevant sections provide further information.