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 openshift-docs@redhat.com
-
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. 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).
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.
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.
/ /topic_dir1 /subtopic_dir1 /subtopic_dirN /topic_dir/topic1.adoc /topic_dir/topicN.adoc /topic_dir/subtopic_dir1/topic1.adoc /topic_dir/subtopic_dirN/topicN.adoc /topic_dir/images /topic_dir/images/img1.png /topic_dir/images/imgN.png ... /topic_dir2
Most of the content applies to all four OpenShift products: Origin, Online, Dedicated and Enterprise (some versions of 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.
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:
-
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.
Here is an example of this concept in use:
This first line is unconditionalized, and will appear for all versions. ifdef::openshift-online[] This line will only appear for OpenShift Online. ifdef::openshift-enterprise[] This line will only appear for OpenShift Enterprise. ifdef::openshift-origin,openshift-enterprise[] This line will appear for OpenShift Origin and Enterprise, but not for OpenShift Online or OpenShift Dedicated.
Note that the following limitations exist when conditionalizing text:
-
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 How it all comes together section for information on how to conditionalize whole topics with the metadatayaml
file. -
Avoid using
ifndef/endif
. As of writing, it’s use is broken and buggy.
With the combination of conditionalizing content within topics with
ifdef/endif
and conditionalizing whole topics with the
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 -
enterprise-N.N
- OpenShift Enterprise support releases -
The
dedicated
andonline
branches are built using the enterprise version that they correspond to.
On a 6 hourly 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 after 6 hours.
Note
|
All OpenShift content development occurs on the |
The documentation build system reads the _distro_map.yml
to figure out which branches to build and then the _topic_map.yml
metadata file for each of the branches
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 _topic_map.yml
metadata file in
order to be processed by the build system.
The format of this file is as indicated:
--- //(1) Name: Origin of the Species (2) Dir: origin_of_the_species (3) Distros: all (4) Topics: - Name: The Majestic Marmoset (5) File: the_majestic_marmoset (6) Distros: all - Name: The Curious Crocodile File: the_curious_crocodile Distros: openshift-online,openshift-enterprise (7) - Name: The Numerous Nematodes Dir: the_numerous_nematodes (8) Topics: - Name: The Wily Worm (9) File: the_wily_worm - Name: The Acrobatic Ascarid <= Sub-topic 2 name File: the_acrobatic_ascarid <= Sub-topic 2 file under <group dir>/<subtopic dir>
-
Record separator at the top of each topic group
-
Display name of topic group
-
Directory name of topic group
-
Which OpenShift versions this topic group is part of
-
Topic name
-
Topic file under the topic group dir without
.adoc
-
Which OpenShift versions this topic is part of
-
This topic is actually a subtopic group. Instead of a
File
path it has aDir
path andTopics
, just like a top-level topic group. -
Topics belonging to a subtopic group are listed just like regular topics with a
Name
andFile
.
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.
-
First, you should Install and set up the tools and software on your workstation so that you can contribute.
-
Next, we recommend that you 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 create or edit content topic describes how you can do this by creating a working branch.