Skip to content

doc_guidelines.adoc

Latest commit

 

History

History
2293 lines (1732 loc) · 89.5 KB

doc_guidelines.adoc

File metadata and controls

2293 lines (1732 loc) · 89.5 KB

Documentation guidelines

Table of Contents

The documentation guidelines for OpenShift 4 build on top of the Red Hat modular docs reference guide.

Note

These Documentation guidelines are primarily concerned with the modular structure and AsciiDoc/AsciiBinder requirements for building OpenShift documentation. For general style guidelines in OpenShift docs, see the following:

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.

General file guidelines

  • Set your editor to strip trailing whitespace.

  • Do not hard wrap lines at 80 characters (or at any other length).

    It is not necessary to update existing content to unwrap lines, but you can remove existing hard wrapping from any lines that you are currently working in.

    Tip

    In the Pulsar editor, you can use Ctrl+J to undo hard wrapping on a paragraph.

Assembly file metadata

Every assembly file must contain the following metadata at the top, with no blank lines, except where noted:

:_mod-docs-content-type: ASSEMBLY                               (1)
[id="<assembly-anchor-id>"]                                     (2)
= Assembly title                                                (3)
include::_attributes/common-attributes.adoc[]                   (4)
:context: <assembly-context>                                    (5)
                                                                (6)
toc::[]                                                         (7)

  1. The content type for the file. For assemblies, always use :_mod-docs-content-type: ASSEMBLY. Place this attribute before the anchor ID or, if present, the conditional that contains the anchor ID.

  2. A unique (within OpenShift docs) anchor ID for this assembly. Use lowercase and hyphens, for example: cli-developer-commands.

  3. Human readable title (notice the = top-level header).

    Note

    • Do not use backticks or other markup in assembly headings. You can use backticks or other markup in the title for a block, such as a code block .Example or a table .Description title.

    • Do not use "Optional:" to prefix an assembly title. According to IBM Style Guide, this practice is reserved for optional steps and code callouts.

    • With content reuse and modular documentation, you cannot be certain that all future use of an assembly will remain optional. For more information, see "Indicating optional and conditional steps (Requires IBM Style login)".

    • The assembly title, which is the first line of the document, is the only level 1 ( = ) title. Section headers within the assembly must be H2 ("Level 1" in AsciiDoc terminology), formatted as ==. When you include modules, you must add leveloffsets in the include statements. You can manually add more H2 (==) section headers in the assembly.

  4. Includes attributes common to OpenShift docs.

    Note

    • The {product-title} and {product-version} common attributes are not defined in the _attributes/common-attributes.adoc file. Those attributes are pulled by AsciiBinder from the distro mapping definitions in the _distro_map.yml file. See Product title and version and attribute files for more information on this topic.

    • If you use a variable in the title of the first assembly in a section, move the include attributes directive above the anchor ID in this assembly. Otherwise, the variable will not render correctly on our documentation portals. For example:

      :_mod-docs-content-type: ASSEMBLY
link:_attributes/common-attributes.adoc[role=include]
[id="installing-ibm-cloud-private"]
= Installing a private cluster on {ibm-cloud-title}
:context: installing-ibm-cloud-private

toc::[]

  5. Context used for identifying headers in modules that is the same as the anchor ID. Use lowercase and hyphens, for example cli-developer-commands.

  6. A blank line. You must have a blank line here before the toc::[].

    After the heading block and a single whitespace line, you can include any content for this assembly.

  7. The table of contents for the current assembly.

Module file metadata

Every module should be placed in the modules folder and should contain the following metadata at the top:

// Module included in the following assemblies:
//
// * list of assemblies where this module is included              (1)

:_mod-docs-content-type: <TYPE>                                    (2)
[id="<module-anchor>_{context}"]                                   (3)
= Module title                                                     (4)
                                                                   (5)

  1. List of assemblies in which this module is included.

  2. The content type for the file. Replace <TYPE> with the actual type of the module, CONCEPT, REFERENCE, or PROCEDURE. Place this attribute before the anchor ID or, if present, the conditional that contains the anchor ID.

  3. The anchor ID with _{context} must be lowercase and match the module’s file name.

  4. Human readable title. To ensure consistency in the results of the leveloffset values in include statements, you must use a level 1 heading ( = ) for the module title.

    Note

    • Do not use backticks or other markup in module headings. You can use backticks or other markup in the title for a block, such as a code block .Example or a table .Description title.

    • Do not use "Optional:" to prefix a module title. According to IBM Style, this practice is reserved for optional steps and code callouts.

    • With content reuse and modular documentation, you cannot be certain that all future use of a module will remain optional. For more information, see "Indicating optional and conditional steps (Requires IBM Style login)".

  5. You must include a blank line after H1 ("Level 0" in AsciiDoc terminology) headings.

Text snippet file metadata

Every text snippet should be placed in the snippets/ folder and should contain the following metadata at the top:

// Text snippet included in the following assemblies: (1)
//
// * list of assemblies where this text snippet is included
//
// Text snippet included in the following modules:    (2)
//
// * list of modules where this text snippet is included

:_mod-docs-content-type: SNIPPET                               (3)

  1. List of assemblies in which this text snippet is included.

  2. List of modules in which this text snippet is included.

  3. The content type for the file. For snippets, always use :_mod-docs-content-type: SNIPPET. Place this attribute before the anchor ID, the conditional that contains the anchor ID, or the first line of body text.

Note

An anchor ID and human readable title are not required metadata. This type of component is text only and not intended to be published or cross referenced on its own. See Writing text snippets.

Example:

// Text snippet included in the following assemblies:
//
// * installing/installing_aws/ipi/installing-aws-default.adoc
// * installing/installing_azure/installing-azure-default.adoc
// * installing/installing_gcp/installing-gcp-default.adoc

:_mod-docs-content-type: SNIPPET
In {product-title} version {product-version}, you can install a cluster on {cloud-provider-first} ({cloud-provider}) that uses the default configuration options.

Content type attributes

Each .adoc file must contain a :_mod-docs-content-type: attribute in its metadata that indicates its file type. This information is used by some publication processes to sort and label files.

Add the attribute from the following list that corresponds to your file type:

  • :_mod-docs-content-type: ASSEMBLY

  • :_mod-docs-content-type: CONCEPT

  • :_mod-docs-content-type: PROCEDURE

  • :_mod-docs-content-type: REFERENCE

  • :_mod-docs-content-type: SNIPPET

  • :_mod-docs-content-type: ATTRIBUTES (Only for attributes files)

Place the attribute in the file metadata. The following list describes the best attribute placement options:

  1. Directly before the first anchor ID in a file

  2. If the first anchor ID is enclosed in a conditional, before the conditional

  3. Between the list of assemblies in which this module is included and the first line of body text

The metadata examples contain sample placement for each file type, assembly, module, and snippet.

Attribute files

All attribute files must be placed in the _attributes directory. In most cases involving OpenShift Container Platform or OKD, add attributes to the common-attributes.adoc file instead of creating or using a separate attributes file. Before you add an attribute, review the contents of the common-attributes.adoc file to ensure that it is not already defined.

When creating a new attribute file, define :_mod-docs-content-type: ATTRIBUTES in the file metadata. Make sure that the content type attribute is on a line by itself in the beginning lines of the file.

Important

If you think that you need a separate attributes file, check with the docs team before you create it.

It is acceptable to group related attributes in the common-attributes.adoc file under a comment, as shown in the following example:

//gitops
:gitops-title: Red Hat OpenShift GitOps
:gitops-shortname: GitOps

It is also acceptable to enclose attributes in a distro-based conditional, but you must place attribute definitions for the openshift-enterprise distro first. The following example shows how to set a different value for the :op-system-base: attribute for OKD:

:op-system-base: RHEL
Note

When backporting content that contains IBM-related attributes to enterprise-4.13 and earlier branches, you might need to create manual cherry picks because IBM-related attributes names are not consistent with later release branches.

Assembly/module file names

Try to shorten the file name as much as possible without abbreviating important terms that may cause confusion. For example, the managing-authorization-policies.adoc file name would be appropriate for an assembly titled "Managing Authorization Policies".

Directory names

When creating a new directory, follow these guidelines:

  • Use underscores to separate multiple-word directory names, for example, backup_and_restore.

  • Create the symbolic links for the images, modules, snippets and _attributes directories. See Symbolic links for instructions.

  • Use the CLI (mkdir <directory_name>) instead of an editor, to avoid potential syncing issues.

  • Do not copy another directory or its symbolic links when creating the new directory, to avoid issues with the symbolic links.

  • Do not create or rename a top-level directory in the repository and topic map without checking with the docs program manager first. If a book is being created or modified, there are changes on the Customer Portal that must also be made.

Symbolic links

When creating a new directory or subdirectory, you must create these four symbolic links in it:

  • An images symbolic link to the top-level images/ directory

  • A modules symbolic link to the top-level modules/ directory

  • A snippets symbolic link to the top-level snippets/ directory

  • An _attributes symbolic link to the top-level _attributes/ directory

Important

If these symbolic links aren’t included in an assembly’s directory, any images in that assembly or its modules are not included properly when building the docs.

To create the symbolic links:

  1. Navigate to the directory that you need to add the links in.

  2. Use the following command to create a symbolic link:

    $ ln -s <target_directory> <link_name>

    For example, if you are creating the links in a directory that is two levels deep, such as cli_reference/openshift_cli, use the following commands:

    [openshift-docs ~]$ cd cli_reference/openshift_cli
[openshift_cli ~]$ ln -s ../../images/ images
[openshift_cli ~]$ ln -s ../../modules/ modules
[openshift_cli ~]$ ln -s ../../snippets/ snippets
[openshift_cli ~]$ ln -s ../../_attributes/ _attributes

    Be sure to adjust the number of levels to back up (../) depending on how deep your directory is.

If you accidentally create an incorrect symbolic link, you can remove that link by using unlink <link_name>. For example, the following commands unlink an incorrect images symbolic link in the cli_reference/openshift_cli directory:

[openshift-docs ~]$ cd cli_reference/openshift_cli
[openshift_cli ~]$ unlink images

Assembly/module titles and section headings

Use sentence case in all titles and section headings. See http://www.titlecase.com/ or https://convertcase.net/ for a conversion tool.

Try to be as descriptive as possible with the title or section headings without making them unnecessarily long. For assemblies and task modules, use a gerund form in headings, such as:

  • Creating

  • Managing

  • Using

Do not use "Overview" as a heading.

Do not use backticks or other markup in assembly or module headings.

Do not use special characters or symbols in titles. Symbols and special characters in titles can cause rendering errors in the HTML output.

Use only one Level 0 (=) heading in any file. Level 0 headings map to an H1 or <h1> in HTML.

Do not use Level 2 (H3) headings (===) or lower in any files.

Anchoring titles and section headings

All titles and section headings must have an anchor ID. The anchor ID must be similar to the title or section heading. Do not include line spaces between the anchor ID and the section title.

Example anchor ID and heading
[id="configuring-alert-notifications"] (1)
= Configuring alert notifications (2)

  1. Anchor ID

  2. Title/section heading

The following anchor IDs also require use of the _{context} variable:

  • All headings in module files

  • Only subsections in assembly files (but not the Level 0 heading/main title)

When called, the _{context} variable is resolved into the value declared in the :context: attribute in the corresponding assembly file. This enables cross-referencing of IDs in context to a specific assembly and is useful when a module is included in multiple assemblies.

Note

The {context} variable must be preceded by an underscore (_) when declared in an anchor ID.

Anchoring in assembly files

Assembly titles (Level 0 headings)

For the single Level 0 heading (=) of an assembly file, do not add a _{context} variable to the end of the anchor ID.

Example anchor ID for the Level 0 heading of an assembly file
[id="configuring-alert-notifications"]
= Configuring alert notifications
Note

This guideline includes an exception to the Red Hat modular docs reference guide, which shows including the {context} variable for Level 0 headings of assemblies as well.

The anchor ID for the assembly title should match the :context: set in the assembly file metadata.

Assembly subsections (Level 1 headings)

For any Level 1 subsections in an assembly (i.e. ==), add a _{context} variable to the end of anchor IDs:

Example anchor ID for a Level 1 heading (subsection) of an assembly file
[id="editing-alerts_{context}"]
== Editing alerts

This ensures a unique anchor ID across the repo.

Do not use H3 headings (===) or lower in any files.

Anchoring in module files

You must add the _{context} variable to the end of each anchor ID in module files, for any section level:

Example anchor ID for a module file Level 0 (=) heading/main title
[id="sending-notifications-to-external-systems_{context}"]
= Sending notifications to external systems
Example anchor ID for a Level 1 (==) subsection heading
[id="deployment-scaling-benefits_{context}"]
== Deployment and scaling benefits

Anchoring "Prerequisites", "Additional resources", and "Next steps" titles in assemblies

For anchor IDs of "Prerequisites", "Additional resources", and "Next steps" titles in assemblies, use the prefixes prerequisites_, additional-resources_, or next-steps_ followed by the {context} variable. Using this variable automatically matches the value assigned to the :context: attribute in the assembly, which ensures a unique ID across the repo. Use an underscore (_) between the prefix and {context} variable.

Example unique anchor ID for a "Prerequisites" title
[id="prerequisites_{context}"]
== Prerequisites
Example unique anchor ID for an "Additional resources" title
[role="_additional-resources"]
[id="additional-resources_{context}"]
== Additional resources
Example unique anchor ID for a "Next steps" title
[id="next-steps_{context}"]
== Next steps

Discrete headings

Do not use discrete headings. If you have several short subjects to talk about that you want headings on, you can use list formatting. You could also consider bulleted lists, or revising your overall document structure to highlight the topics with headings.

Example list formatting in a module or assembly
OVN node switch::
A virtual switch named `<node-name>`.

Writing assemblies

An assembly is a collection of modules that describes how to accomplish a user story. Module content is added to an assembly using the include directive. The include directive includes contents from another file in the current document. Files can be modules or snippets formatted in AsciiDoc, or another text format such as YAML.

An include directive must always be on its own line and be followed by a blank line.

Standard module include syntax
include::modules/module-filename.adoc[leveloffset=+1] (1)
                                                      (2)

  1. [leveloffset=] is relative, and changes the header level of included content.

  2. You must include a blank line after each include:: statement.

Important

Including lines by content ranges can lead to content errors when the included file is subsequently updated and is not permitted.

Avoid nesting assemblies in other assembly files. You can create more complicated document structures by modifying the topic maps.

For more information about forming assemblies, see the Red Hat modular docs reference guide and the assembly template.

Note

When using the "Prerequisites", "Next steps", or "Additional resources" headings in an assembly, use == formatting, such as == Prerequisites or == Additional resources. Use of this heading syntax at the assembly level indicates that the sections relate to the whole assembly.

Only use . formatting (.Additional resources) to follow a module in an assembly. Because you cannot use the xrefs in modules, this functions as a trailing include at the assembly level, where the . formatting of the include statement indicates that the resource applies specifically to the module and not to the assembly.

Writing concepts

A concept contains information to support the tasks that users want to do and must not include task information like commands or numbered steps. In most cases, create your concepts as individual modules and include them in appropriate assemblies.

Avoid using gerunds in concept titles. "About <concept>" is a common concept module title.

For more information about creating concept modules, see the Red Hat modular docs reference guide and the concept template.

Writing procedures

A procedure contains the steps that users follow to complete a single 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".

Important

Most modules cannot contain xrefs. However, the following situations have an exception to allow xrefs in modules as long as the module is only ever included once from one assembly:

  • Release notes modules

  • Modules created from assembly content for DITA migration compliance

Use version attributes for the maintainability of xrefs and links whenever you can.

For more information about writing procedures, see the Red Hat modular docs reference guide and the procedure template.

Note

When needed, use the <.section_title> syntax suppress TOC formatting within a module, for example, .Prerequisites, .Procedure, .Next steps, or .Additional resources. Do not use the heading-level syntax, such as ==, for these headings in modules.

Writing text snippets

A text snippet is an optional component that lets you reuse content in multiple modules and assemblies. Text snippets are not a substitute for modules but instead are a more granular form of content reuse. While a module is content that a reader can understand on its own (like an article) or as part of a larger body of work (like an assembly), a text snippet is not self-contained and is not intended to be published or cross referenced on its own.

Important

Text snippets cannot contain xrefs. If you must use a link in your snippet, use the link attribute type and treat it as an external reference. It is recommended to use version attributes for maintainability of the link.

In the context of modules and assemblies, text snippets do not include headings or anchor IDs. Examples include the following:

  • Admonitions that appear in multiple modules.

  • An introductory paragraph that appears in multiple assemblies.

  • The same series of steps that appear in multiple procedure modules.

  • A deprecation statement that appears in multiple sets of release notes.

Example:

You could write the following paragraph once and include it in each assembly that explains how to install a cluster using the installer-provisioned default values:

In {product-title} version {product-version}, you can install a cluster on {cloud-provider-first} ({cloud-provider}) that uses the default configuration options.
Note

In the example, cloud-provider-first and cloud-provider are not defined by the common-attributes module. If you use an attribute that is not common to OpenShift docs, make sure to define it locally in either the assembly or module, depending on where the text snippet is included. Because of this, consider adding all attributes that you add to snippets to the common-attributes.adoc file.

For more information about creating text snippets, see the Red Hat modular docs reference guide.

Automatically generated content

The following content is automatically generated in each release and must not be manually edited:

  • The OpenShift CLI (oc) command references modules/oc-by-example-content.adoc and modules/oc-adm-by-example-content.adoc.

  • The following API references content in the rest_api folder: the contents of all <topic>_apis subfolders and the rest_api/objects/index.adoc and rest_api/index.adoc assemblies.

  • OpenShift Virtualization runbook modules: modules/virt-runbook-<runbook>.adoc.

Note

If the content in these files needs to be updated, the update must be made in the applicable code repository where these files are generated from. The updates are reflected when the files are generated the next time, for example a future release. For help with where to make the updates, you can contact Andrea Hoffer for the CLI docs, Jason Boxman for the API docs, or Avital Pinnick for the OpenShift Virtualization runbooks.

Using conscious language

To assist with the removal of the problematic word "master" from the documentation, use the following terminology when referring to OpenShift control plane nodes:

Branch Control plane node reference

All supported versions

Control plane node

You can replace "node" in the preceding examples with "machine", "host", or another suitable description.

In general text, use the term "control plane machine" in place of "master machine"; use the term "compute machine" in place of "worker machine". Be mindful of certain valid code entities, such as master role, worker role, and infra role.

Adding a subsection on making open source more inclusive

Because the link to the "Making open source more inclusive" content has been moved to the footer of docs.redhat.com, do not include a separate module related to this content.

Product title and version

When possible, generalize references to the product name and/or version by using the {product-title} and/or {product-version} attributes. These attributes are pulled by AsciiBinder from the OpenShift distribution, or distro, mapping definitions in the _distro_map.yml file.

The {product-title} comes from the first name: field in a distro mapping, while the associated {product-version} comes from the name: fields on any branches: defined.

How these attributes render is dependent on which distro and branch build you are viewing. The following table shows the current distros and the possible values for {product-title} and {product-version}, depending on the branch:

Distro {product-title} {product-version}

openshift-origin

OKD

  • 3.6, 3.7, 3.9, 3.10, 3.11

  • 4.8, 4.9, 4.10, 4.11, 4.12, 4.13, 4.14, 4.15, 4.16, 4.17, 4.18, 4.19, 4.20, 4.21

  • 4 for the latest/ build from the main branch

openshift-enterprise