From 620ba300ac5ed8cff65c840ee8106f4adbfadedf Mon Sep 17 00:00:00 2001
From: Jared Smith
Date: Mar 02 2018 18:10:24 +0000
Subject: Merge branch 'master' of ssh://pagure.io/fedora-docs/documentation-guide
---
diff --git a/_distro_map.yml b/_distro_map.yml
index 62870ad..e55d33e 100644
--- a/_distro_map.yml
+++ b/_distro_map.yml
@@ -1,11 +1,11 @@
---
fedora:
- name: Fedora Installation Guide
+ name: Fedora Documentation Guide
author: Fedora Documentation Project
site: main
site_name: Home
site_url: https://docs.fedoraproject.org/
branches:
master:
- name: Rawhide
- dir: master
+ name: documentation-guide
+ dir: documentation-guide
diff --git a/_topic_map.yml b/_topic_map.yml
index e8c7d14..56501e0 100644
--- a/_topic_map.yml
+++ b/_topic_map.yml
@@ -25,12 +25,12 @@ Name: Fedora Documentation Guide
Dir: en-US
Topics:
- Name: Contributing
- File: contributing
+ File: index
- Name: Pull Requests
File: pr
- Name: Publishing Translations
File: publishing-translation
- - Name: Orginization
+ - Name: Organization
File: repo-org
- Name: Tools
File: tools
diff --git a/en-US/contributing.adoc b/en-US/contributing.adoc
deleted file mode 100644
index a680309..0000000
--- a/en-US/contributing.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-= Contribute to Fedora Documentation
-
-== Different Ways to Contribute
-
-There are a few different ways you can contribute to Fedora
-documentation. While all of these are great ways to contribute, we've
-listed them in the order of maximum impact.
-
-* If you would like to do the work yourself, or if it is a substantial
- change, then you you should clone the repository, make your changes,
- and submit a pull request (PR). Each PR should have closely-related
- changes. In particular, it is a good idea to use separate PRs
- for bugfix changes (for an old or current release) vs enhancement
- changes (for an upcoming new release). Further information about
- link:pr.adoc[PRs is available] in this documentation set.
-* Create an issue in https://pagure.io/[pagure.io] in the appropriate
- document's repository. See xref:repository-list[Repository List]
- below for more details.
-* Email the Fedora documentation team: docs@lists.fedoraproject.org
-
-
-[[repository-list]]
-== Repository List
-
-Major documents and/or documentation sets are separated
-into separate repositories. All repositories are stored in
-https://pagure.io/[pagure.io].
-
-The major documents and documentations sets are:
-
-* Installation Guide - https://pagure.io/fedora-docs/install-guide
-* Release Notes - https://pagure.io/fedora-docs/release-notes
-* System Administrator's Guide - https://pagure.io/fedora-docs/system-administrators-guide
-
-This document is stored in https://pagure.io/fedora-docs/documentation-guide
diff --git a/en-US/index.adoc b/en-US/index.adoc
new file mode 100644
index 0000000..234be01
--- /dev/null
+++ b/en-US/index.adoc
@@ -0,0 +1,31 @@
+= Contribute to Fedora documentation
+
+== Different ways to contribute
+
+There are a few different ways you can contribute to Fedora documentation.
+While all of these are great ways to contribute, we've listed them in the order of maximum impact.
+
+* To do the work yourself, or if it is a substantial change, you should clone the repository, make your changes, and submit a pull request (PR).
+Each PR should have closely-related changes.
+In particular, it is a good idea to use separate PRs for bug-fix changes (for an old or current release) vs enhancement changes (for an upcoming new release).
+Further information about link:pr.html[PRs is available].
+
+* Create an issue in https://pagure.io/[pagure.io] in the repository of the appropriate document.
+See the link:#repository-list[Fedora Docs repository list] below for more details.
+
+* Email the Fedora documentation team: docs@lists.fedoraproject.org.
+
+
+[[repository-list]]
+== Repository list
+
+Major documents or documentation sets are separated into separate repositories.
+All repositories are stored in https://pagure.io/[pagure.io].
+
+The major documents and documentations sets are:
+
+* Release Notes - https://pagure.io/fedora-docs/release-notes
+* Installation Guide - https://pagure.io/fedora-docs/install-guide
+* System Administrator's Guide - https://pagure.io/fedora-docs/system-administrators-guide
+
+This document is stored in https://pagure.io/fedora-docs/documentation-guide.
diff --git a/en-US/pr.adoc b/en-US/pr.adoc
index cd17b0f..b6afde3 100644
--- a/en-US/pr.adoc
+++ b/en-US/pr.adoc
@@ -1,108 +1,91 @@
-= Pull Request Guidelines and Workflow
+= Understanding pull-request workflow
+
+Fedora documentation uses Git to store source files and facilitate collaboration. Using so-called pull requests is an established workflow for the Git version control system. This section provides basic guidelines for Git use and outlines a workflow to be followed when working with documentation repositories.
== Guidelines
+Learn about basic best practices to make collaboration streamlined.
+
=== Keep writing
-Provided a clear statement of the changes that are included in the
-PR. This will help the right people see your changes and will aid in
-getting them looked at faster.
+Provide a clear statement of the changes that are included in the _pull request_ (PR).
+This will help the right people see your changes and will aid in getting them reviewed faster.
=== Keep it small
-Giant dumps or edits make reviews a lengthy and time consuming
-process. For the sake of the review, and yourself keep PRs as small as
-you can while still making sense.
+Giant dumps or edits make reviews a lengthy and time consuming process.
+For the sake of the review and yourself, keep PRs as small as you can while still making sense.
-If you are providing a large number
-of edits to existing documents attempt to group them by section, or by
-the type of correction you are making. If you are adding new content
-keep limit each PR to a new page or section.
+To provide a large number of edits to existing documents, group them by section, or by the type of correction you are making.
+If you are adding new content keep limit each PR to a new page or section.
-However, each PR must be fully self-contained. The balance you want
-to strike is between readability and manageability of the PR and of
-ensuring that each PR, when committed, leaves the documentation logical
-and complete.
+However, each PR must be fully self-contained.
+The balance you want to strike is between readability and manageability of the PR and of ensuring that each PR, when committed, leaves the documentation logical and complete.
=== Keep it clean
-Histories are an extremely valuable part of using a version control
-system, but providing a history of your small changes may not be as
-useful. If you are the type of person who commits often locally, and
-tend to have lots of commits making up your PR look at using `git rebase`
-to combine commits into a smaller number of more verbose commits.
+Histories are an extremely valuable part of using a version control system, but providing a history of your small changes may not be as useful.
+If you are the type of person who commits often locally, and you tend to have lots of commits making up your PRs, look at using `git{nbsp}rebase` to combine commits into a smaller number of more verbose commits.
=== Keep paying attention
-As the PR submitter your job is not done once you start the process. Make
-sure to stay engaged and work with the people reviewing your changes.
+As the PR submitter, your job is not done once you start the process.
+Make sure to stay engaged and work with the people reviewing your changes.
=== Keep a good attitude
-After putting a lot of work into something, it is natural to take reviews
-as a personal attack. Try and remember that this process is designed to
-help create the best possible end product for Fedora. It is important
-to keep that in mind and not to let it discourage you from continuing on.
+After putting a lot of work into something, it is natural to take reviews as a personal attack.
+Try and remember that this process is designed to help create the best possible end-product for Fedora.
+It is important to keep that in mind and not to let it discourage you from continuing.
== Workflow
-The sources for Fedora's documentation are stored in git repositories
-at https://pagure.io. Contributions are accepted via `pull requests`,
-which merge changes from your copy of the repository into the original.
+The sources for Fedora's documentation are stored in Git repositories at link:https://pagure.io[pagure.io].
+Contributions are accepted via _pull requests_, which merge changes from your copy of the repository into the original.
-- Install the required link:tools.adoc[tools].
-
-- Log into `pagure` and click the `Fork` button at the upper right hand
- corner of a repository. You now have a personal copy of the repo,
- called a `fork`.
+. Install the required link:tools.html[tools].
-- Clone your repository using the SSH URL.
+. Log into Pagure and click the *Fork* button in the upper right-hand corner of a repository.
+You now have a personal copy of the repo, called a _fork_.
+. Clone your fork of the repository using the *SSH* URL.
++
....
-git clone ssh://git@pagure.io/forks//documentation-guide.git
-cd documentation-guide
+$ git clone ssh://git@pagure.io/forks//documentation-guide.git
+$ cd documentation-guide
....
-- Create a branch to contain your work. This makes it easier for others
- to pull from your repo without disrupting their existing content.
- You can name the branch anything, but something that correlates to
- the work you'll be doing is best.
-
+. Create a branch to contain your work.
+This makes it easier for others to pull from your repo without disrupting their existing content.
+You can name the branch anything, but something that correlates to the work you'll be doing is best.
++
....
-git checkout -b pull_request_workflow
+$ git checkout -b pull_request_workflow
....
-- Make your changes using the editor of your choice. Add a commit for
- each distinct change.
-
+. Make your changes using the editor of your choice. Add a commit for each distinct change.
++
....
-git add en-US/pr.adoc
-git commit -m 'begin describing pull request workflow'
+$ git add en-US/pr.adoc
+$ git commit -m 'begin describing pull request workflow'
....
-- FIXME - how to build previews
-
-- Push your changes to `pagure`.
+. #FIXME# - how to build previews
+. Push your changes to Pagure.
++
....
-git push origin
+$ git push origin
....
-- FIXME - add how to keep your branch up to date with other changes
- while working and how to do a final rebase to avoid merge conflicts
- (by adding a `git remote`)
+. #FIXME# - add how to keep your branch up to date with other changes while working and how to do a final rebase to avoid merge conflicts (by adding a `git remote`).
-- FIXME - add how to squash commits
+. #FIXME# - add how to squash commits.
-- The new branch will now appear in your fork on pagure. Once you have
- pushed a cohesive set of changes, press the `New PR` button to start
- a new pull request. `pagure` will send your changes for review after
- you fill out the form and press `Create`.
+. The new branch will now appear in your fork on pagure.
+Once you have pushed a cohesive set of changes, press the *New PR* button to start a new pull request.
+Pagure will send your changes for review after you fill out the form and press *Create*.
-- Work with your reviewer to address any concerns. Subsequent commits
- pushed to this branch of your fork will be automatically included in
- the pull request.
+. Work with your reviewer to address any concerns. Subsequent commits pushed to this branch of your fork will be automatically included in the pull request.
-- Your changes get merged by the reviewer. Congratulations! Reward
- yourself with a beer, you've earned it! Soon you'll also earn a
- https://badges.fedoraproject.org/[Fedora Badge]
+. Your changes get merged by the reviewer. Congratulations! Reward yourself with your favorite treat, you've earned it! Soon you'll also earn a link:https://badges.fedoraproject.org/[Fedora Badge].
diff --git a/index-main.html b/index-main.html
index f8801fc..e3ae701 100644
--- a/index-main.html
+++ b/index-main.html
@@ -29,17 +29,14 @@