Merge pull request #56857 from adellape/actualsentence

Author: adellape

contributing_to_docs/doc_guidelines.adoc

@@ -4,7 +4,17 @@ include::_attributes/common-attributes.adoc
 :toc: macro
 
 The documentation guidelines for OpenShift 4 build on top of the
-link:https://redhat-documentation.github.io/modular-docs/[Red Hat modular docs reference guide].
+link:https://redhat-documentation.github.io/modular-docs/[_Red Hat modular docs reference guide_].
+
+[NOTE]
+====
+These _Documentation guidelines_ are primarily concerned with the modular structure and AsciiDoc / AsciiBinder requirements for building OpenShift documention. For general style guidelines in OpenShift docs, see the following:
+
+* Primary source: link:https://www.ibm.com/docs/en/ibm-style[_IBM Style_]
+* Supplementary source: link:https://redhat-documentation.github.io/supplementary-style-guide/[_Red Hat supplementary style guide for product documentation_]
+
+When looking for style guidance, reference the _Red Hat supplementary style guide for product documentation_ first, because it overrides certain guidance from the _IBM Style_ guide.
+====
 
 toc::[]
 
@@ -184,7 +194,7 @@ If you create a directory with a multiple-word name, separate each word with an
 
 [NOTE]
 ====
-Do not italicize user-replaced values. This guideline is an exception to the link:https://redhat-documentation.github.io/supplementary-style-guide/#user-replaced-values[Red Hat supplementary style guide].
+Do not italicize user-replaced values. This guideline is an exception to the link:https://redhat-documentation.github.io/supplementary-style-guide/#user-replaced-values[_Red Hat supplementary style guide for product documentation_].
 ====
 
 Do not create or rename a top-level directory in the repository and topic map without checking with the docs program manager first.
@@ -339,7 +349,7 @@ An _assembly_ is a collection of modules that describes how to accomplish a user
 Avoid link:https://redhat-documentation.github.io/modular-docs/#nesting-assemblies[nesting assemblies] in other assembly files. You can create more complicated document structures by modifying the link:https://github.com/openshift/openshift-docs/tree/main/_topic_maps[topic maps].
 
 For more information about forming assemblies, see the
-link:https://redhat-documentation.github.io/modular-docs/#forming-assemblies[Red Hat modular docs reference guide] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc[assembly template].
+link:https://redhat-documentation.github.io/modular-docs/#forming-assemblies[_Red Hat modular docs reference guide_] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc[assembly template].
 
 [NOTE]
 ====
@@ -358,15 +368,15 @@ Avoid using gerunds in concept titles. "About <concept>"
 is a common concept module title.
 
 For more information about creating concept modules, see the
-link:https://redhat-documentation.github.io/modular-docs/#creating-concept-modules[Red Hat modular docs reference guide] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc[concept template].
+link:https://redhat-documentation.github.io/modular-docs/#creating-concept-modules[_Red Hat modular docs reference guide_] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc[concept template].
 
 == Writing procedures
 A _procedure_ contains the steps that users follow to complete a process or task. Procedures contain ordered steps and explicit commands. In most cases, create your procedures as individual modules and include them in appropriate assemblies.
 
 Use a gerund in the procedure title, such as "Creating".
 
 For more information about writing procedures, see the
-link:https://redhat-documentation.github.io/modular-docs/#creating-procedure-modules[Red Hat modular docs reference guide] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc[procedure template].
+link:https://redhat-documentation.github.io/modular-docs/#creating-procedure-modules[_Red Hat modular docs reference guide_] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc[procedure template].
 
 [NOTE]
 ====
@@ -399,7 +409,7 @@ In the example, `cloud-provider-first` and `cloud-provider` are not defined by t
 ====
 
 For more information about creating text snippets, see the
-link:https://redhat-documentation.github.io/modular-docs/#using-text-snippets[Red Hat modular docs reference guide]
+link:https://redhat-documentation.github.io/modular-docs/#using-text-snippets[_Red Hat modular docs reference guide_].
 
 [id="Auto-generated-content"]
 == Auto-generated content
@@ -677,7 +687,7 @@ Links can be used to cross-reference internal assemblies or send readers to exte
 In OpenShift docs:
 
 * All links to internal content is created using `xref` and **must have an anchor ID**.
-* Only use `xref` in assemblies, not modules.
+* Only use `xref` in assemblies, not in modules.
 * All links to external websites are created using `link`.
 
 [IMPORTANT]
@@ -693,36 +703,31 @@ To provide an example URL path that you do not want to render as a hyperlink, us
 ....
 
 === Internal cross-references
-Whenever possible the link to another assembly should be part of the actual sentence.
-Avoid creating links as a separate sentence that begins with "See [this assembly] for more information on x".
 
-[NOTE]
-====
-Use the relative file path (from the file you are editing, to the file you are linking to),
-even if you are linking to the same directory that you are writing in. This makes search and replace
-operations to fix broken links much easier.
+Use the relative file path (from the file you are editing to the file you are linking to), even if you are linking to the same directory that you are writing in. This makes search and replace operations to fix broken links much easier.
 
-For example, if you are writing in *_architecture/core_concepts/deployments.adoc_* and you want to
-link to *_architecture/core_concepts/routes.adoc_* then you must include the path back to the first
-level of the assembly directory:
+For example, if you are writing in `architecture/core_concepts/deployments.adoc` and you want to link to `architecture/core_concepts/routes.adoc`, then you must include the path back to the first level of the assembly directory:
 
 ----
 xref:../../architecture/networking/routes.adoc#architecture-core-concepts-routes
 ----
+
+[NOTE]
+====
+In OpenShift docs, you can only use `xref` in assemblies, not in modules.
 ====
 
 .Markup example of cross-referencing
 ----
-Rollbacks revert part of an application back to a previous deployment. Rollbacks can be performed using the REST API or
-the xref:../cli_reference/openshift_cli/get_started_cli.adoc#installing-openshift-cli[OpenShift CLI].
+For more information, see xref:../dev_guide/application_lifecycle/new_app.adoc#dev-guide-new-app[Creating an application].
 
-Before you can create a domain, you must first xref:../dev_guide/application_lifecycle/new_app.adoc#dev-guide-new-app[create an application].
+Rollbacks can be performed using the REST API or the xref:../cli_reference/openshift_cli/get_started_cli.adoc#installing-openshift-cli[OpenShift CLI].
 ----
 
 .Rendered output of cross-referencing
-> Rollbacks revert part of an application back to a previous deployment. Rollbacks can be performed using the REST API or the xref:../cli_reference/openshift_cli/get_started_cli.adoc#installing-openshift-cli[OpenShift CLI].
+> For more information, see xref:../dev_guide/application_lifecycle/new_app.adoc#dev-guide-new-app[Creating an application].
 >
-> Before you can create a domain, you must first xref:../dev_guide/application_lifecycle/new_app.adoc#dev-guide-new-app[create an application].
+> Rollbacks can be performed using the REST API or the xref:../cli_reference/openshift_cli/get_started_cli.adoc#installing-openshift-cli[OpenShift CLI].
 
 === Links to external websites
 
@@ -779,12 +784,12 @@ xref:../dir/<filename>.adoc#anchor-id[friendly title]
 For example, if you are working on `bar.adoc` and you want to link to `zig.adoc`, do it this way:
 
 ----
-xref:../baz/zig.adoc#baz-zig[see the ZIG manual for more]
+For more information, see the xref:../baz/zig.adoc#baz-zig[ZIG manual].
 ----
 
 [NOTE]
 ====
-You must use the .adoc extension in order for the link to work correctly and you must specify an anchor ID.
+You must use the `.adoc` extension in order for the link to work correctly and you must specify an anchor ID.
 ====
 
 == Embedding an external file
@@ -837,7 +842,7 @@ To indicate that a feature is in Technology Preview, include the `snippets/techn
 
 To indicate that a feature is deprecated, include the `modules/deprecated-feature.adoc` file in the feature's assembly, or to each relevant assembly such as for a deprecated Operator, to keep the supportability wording consistent across deprecated features. Provide a value for the `:FeatureName:` variable before you include this module.
 
-See link:https://github.com/openshift/openshift-docs/pull/31776/files[an example] of how this is applied.
+For more information on how this is applied, see link:https://github.com/openshift/openshift-docs/pull/31776/files[this example PR].
 
 == Verification of your content
 All documentation changes must be verified by a QE team associate before merging. This includes executing all "Procedure" changes and confirming expected results. There are exceptions for typo-level changes, formatting-only changes, and other negotiated documentation sets and distributions.
@@ -1973,6 +1978,6 @@ a|
 
 |A footnote is created with the footnote macro. If you plan to reference a footnote more than once, use the ID footnoteref macro. The Customer Portal does not support spaces in the footnoteref. For example, "dynamic PV" should be "dynamicPV".
 
-|See link:http://asciidoctor.org/docs/user-manual/#user-footnotes[Footnotes] for the footnote and footnoteref syntax.
+|For footnote and footnoteref syntax, see link:http://asciidoctor.org/docs/user-manual/#user-footnotes[AsciiDoctor documentation].
 
 |===