Fix rendering issues and cleanup contributing doc

gyj0825 · Dec 9, 2015 · 634a260 · 634a260
1 parent 8da5b9f
commit 634a260
Showing 1 changed file with 93 additions and 29 deletions.
diff --git a/contributing_to_docs/contributing.adoc b/contributing_to_docs/contributing.adoc
@@ -12,17 +12,30 @@ There are a few different ways you can contribute to OpenShift documentation:
 
 * Submit comments at the bottom of each topic (still awaiting implementation)
 * Email the OpenShift documentation team [email protected]
-* https://github.com/openshift/openshift-docs/issues/new[Create an issue in GitHub] 
-* 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 PR
+* https://github.com/openshift/openshift-docs/issues/new[Create an issue in
+GitHub]
+* 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 PR
 
 *What happens when you submit a PR?*
 
-If you make a substantial change and submit a PR in GitHub, your PR will be reviewed by our documentation team. If there are any further changes, updates, or corrections required we will inform you in the PR. When the PR has been reviewed and all changes have been accepted by our documentation team, your PR will be merged.
+If you make a substantial change and submit a PR in GitHub, your PR will be
+reviewed by our
+https://github.com/orgs/openshift/teams/team-documentation[documentation team].
+If there are any further changes, updates, or corrections required, we will
+inform you in the PR. When the PR has been reviewed and all changes have been
+accepted by our documentation team, your PR will be merged.
 
 == Repository organization
-Each top directory in the OpenShift documentation repository can include a collection of top level topics, and/or subdirectories that further contain a second level of topics. The exceptions to this rule are directories whose names start with an underscore (like `_builder_lib` and `_javascripts`), which contain the assets used to generate the finished documentation.
+Each top directory in the OpenShift documentation repository can include a
+collection of top level topics, and/or subdirectories that further contain a
+second level of topics. The exceptions to this rule are directories whose names
+start with an underscore (like `_builder_lib` and `_javascripts`), which contain
+the assets used to generate the finished documentation.
 
-Each top level 'topic' directory contains the topics as asciidoc files, any 'subtopic' subdirectories, and an 'images' directory where all images for that topic are stored. 
+Each top level `<topic>` directory contains the topics as AsciiDoc files, any
+`<subtopic>` subdirectories, and an `images` directory where all images for that
+topic are stored.
 
 ----
 /
@@ -41,21 +54,33 @@ Each top level 'topic' directory contains the topics as asciidoc files, any 'sub
 ----
 
 == Version management
-Most of the content applies to all three OpenShift products: Origin, Online, and Enterprise, so approximately 80% of the content is reused. In many cases, this means that individual topics may need to include or exclude individual paragraphs with respect to a specific OpenShift product. While it is _possible_ to accomplish this solely with Git branches to maintain slightly different versions of a given topic, doing so would make the task of maintaining internal consistency extremely difficult for content contributors.
-
-Git branching is still extremely valuable, and serves the important role of tracking the release versions of documentation for the various OpenShift products.
+Most of the content applies to all three OpenShift products: Origin, Online, and
+Enterprise, so approximately 80% of the content is reused. In many cases, this
+means that individual topics may need to include or exclude individual
+paragraphs with respect to a specific OpenShift product. While it is _possible_
+to accomplish this solely with Git branches to maintain slightly different
+versions of a given topic, doing so would make the task of maintaining internal
+consistency extremely difficult for content contributors.
+
+Git branching is still extremely valuable, and serves the important role of
+tracking the release versions of documentation for the various OpenShift
+products.
 
 === Conditional text between products
-OpenShift documentation uses AsciiDoc's `ifdef/endif` macro to conditionalize and reuse content across the different OpenShift products, down to the single-line level. 
+OpenShift documentation uses AsciiDoc's `ifdef/endif` macro to conditionalize
+and reuse content across the different OpenShift products, down to the
+single-line level.
 
-The supported distribution attributes used with the OpenShift build mechanism are:
+The supported distribution attributes used with the OpenShift build mechanism
+are:
 
 * _openshift-origin_
 * _openshift-online_
 * _openshift-enterprise_
 * _openshift-dedicated_
 
-These attributes can be used by themselves, or in conjunction to conditionalize text within a topic document.
+These attributes can be used by themselves, or in conjunction to conditionalize
+text within a topic document.
 
 Here is an example of this concept in use:
 
@@ -77,31 +102,58 @@ endif::[]
 
 Note that the following limitations exist when conditionalizing text:
 
-1. The `ifdef/endif` blocks have no size limit, however they should not be used to conditionalize an entire topic. If an entire topic file is specific to a given OpenShift distribution, see the link:#how-it-all-comes-together[How it all comes together] section for information on how to conditionalize whole topics with the metadata _yaml_ file.
+1. The `ifdef/endif` blocks have no size limit, however they should not be used
+to conditionalize an entire topic. If an entire topic file is specific to a
+given OpenShift distribution, see the link:#how-it-all-comes-together[How it all
+comes together] section for information on how to conditionalize whole topics
+with the metadata `yaml` file.
 
-2. The `ifdef/endif` blocks cannot be nested. In other words, one conditional block cannot contain other conditional blocks.
+2. The `ifdef/endif` blocks cannot be nested. In other words, one conditional
+block cannot contain other conditional blocks.
 
 == Release branches
-With the combination of conditionalizing content within topics with _ifdef/endif_ and conditionalizing whole topics with the link:#how-it-all-comes-together[metadata _yaml_ file], the `master` branch of this repository always contains a complete set of documentation for all three OpenShift products. However, when and as new versions of an OpenShift product are released, the master branch is merged down to new or existing release branches. Here is the general naming scheme used in the branches:
-
-* `master` - OpenShift Origin latest code; essentially, this is our *working* branch
+With the combination of conditionalizing content within topics with
+`ifdef/endif` and conditionalizing whole topics with the
+link:#how-it-all-comes-together[metadata `yaml` file], the `master` branch of
+this repository always contains a complete set of documentation for all three
+OpenShift products. However, when and as new versions of an OpenShift product
+are released, the `master` branch is merged down to new or existing release
+branches. Here is the general naming scheme used in the branches:
+
+* `master` - OpenShift Origin latest code; essentially, this is our *working*
+branch
 * `origin-N.N` - OpenShift Origin most recent stable release
 * `online` - OpenShift Online most recent release
 * `enterprise-N.N` - OpenShift Enterprise support releases
 
-On a nightly basis, the documentation web sites are rebuilt for each of these branches. This way the published content for each released version of an OpenShift product will remain the same while development continues on the 'master' branch. Additionally, any corrections or additions that are "cherry-picked" into the release branches will show up in the published documentation the next day.
+On a nightly basis, the documentation web sites are rebuilt for each of these
+branches. This way the published content for each released version of an
+OpenShift product will remain the same while development continues on the
+`master` branch. Additionally, any corrections or additions that are
+"cherry-picked" into the release branches will show up in the published
+documentation the next day.
 
 [NOTE]
-All OpenShift content development occurs on the `master`, or *working* branch. Therefore, when submitting your work the PR must be created against the `master` branch. Once it is reviewed that content will then migrate to the corresponding release branches.
+====
+All OpenShift content development occurs on the `master`, or *working* branch.
+Therefore, when submitting your work the PR must be created against the `master`
+branch. Once it is reviewed that content will then migrate to the corresponding
+release branches.
+====
 
 == How it all comes together
-The documentation build system reads the `_build_cfg.yml_` metadata file to construct the content from the source files and publish to the relevant product site at https://docs.openshift.com. The build system _only_ reads this file to determine which topic files to include. Therefore, all new topics that are created must be included in the `_build_cfg.yml_` metadata file in order to be processed by the build system. 
+The documentation build system reads the `&#95;build&#95;cfg.yml` metadata file
+to construct the content from the source files and publish to the relevant
+product site at https://docs.openshift.com. The build system _only_ reads this
+file to determine which topic files to include. Therefore, all new topics that
+are created must be included in the `&#95;build&#95;cfg.yml` metadata file in
+order to be processed by the build system.
 
 === Metadata file format
 The format of this file is as indicated:
 
 ----
---- <1>
+--- //<1>
 Name: Origin of the Species <2>
 Dir:  origin_of_the_species <3>
 Distros: all <4>
@@ -125,20 +177,32 @@ Topics:
 <3> Directory name of topic group
 <4> Which OpenShift versions this topic group is part of
 <5> Topic name
-<6> Topic file under the topic group dir without '.adoc'
+<6> Topic file under the topic group dir without `.adoc`
 <7> Which OpenShift versions this topic is part of
-<8> This topic is actually a subtopic group. Instead of a `File` path it has a `Dir` path and `Topics`, just like a top-level topic group.
-<9> Topics belonging to a subtopic group are listed just like regular topics with a `Name` and `File`.
+<8> This topic is actually a subtopic group. Instead of a `File` path it has a
+`Dir` path and `Topics`, just like a top-level topic group.
+<9> Topics belonging to a subtopic group are listed just like regular topics
+with a `Name` and `File`.
 
 ****
 Notes on *Distros* metadata attribute
 
-* The *Distros* setting is optional for topic groups and topic items. By default, if the *Distros* setting is not used, it is process as if it was set to *Distros: all* for that particular topic or topic group. This means that topic or topic group will appear in all three product documentation. 
-* The *all* value for *Distros* is a synonym for _openshift-origin,openshift-enterprise,openshift-online,openshift-dedicated_.
-* The *all* value overrides other values, so _openshift-online,all_ is processed as *all*
+* The *Distros* setting is optional for topic groups and topic items. By
+default, if the *Distros* setting is not used, it is process as if it was set
+to *Distros: all* for that particular topic or topic group. This means that
+topic or topic group will appear in all three product documentation.
+* The *all* value for *Distros* is a synonym for
+_openshift-origin,openshift-enterprise,openshift-online,openshift-dedicated_.
+* The *all* value overrides other values, so _openshift-online,all_ is processed
+as *all*.
 ****
 
 == Next steps
-* First, you should link:tools_and_setup.adoc[Install and set up the tools and software] on your workstation so that you can contribute.
-* Next, we recommend that you link:doc_guidelines.adoc[review the documentation guidelines] to understand some basic guidelines to keep things consistent across our content.
-* If you are ready to create new content, or want to edit existing content, the link:create_or_edit_content.adoc[create or edit content] topic describes how you can do this by creating a working branch.
+* First, you should link:tools_and_setup.adoc[Install and set up the tools and
+software] on your workstation so that you can contribute.
+* Next, we recommend that you link:doc_guidelines.adoc[review the documentation
+guidelines] to understand some basic guidelines to keep things consistent
+across our content.
+* If you are ready to create new content, or want to edit existing content, the
+link:create_or_edit_content.adoc[create or edit content] topic describes how
+you can do this by creating a working branch.