The documentation guidelines for OpenShift 4 build on top of the Red Hat modular docs reference guide.
- General file guidelines
- Assembly file metadata
- Module file metadata
- Assembly/module file names
- Assembly/Module titles and section headings
- Writing concepts
- Writing tasks
- Product name & version
- Links, hyperlinks, and cross references
- Indicating Technology Preview Features
- Images
- Formatting
- Admonitions
- API object formatting
- Quick markup reference
Every assembly file should contain the following metadata at the top, with no line spacing in between, except where noted:
[id="<unique-heading-for-assembly>"] (1) = Assembly title (2) include::modules/common-attributes.adoc[] (3) :context: <unique-context-for-assembly> (4)
-
A unique (within OpenShift docs) anchor id for this assembly. Example: cli-developer-commands
-
Human readable title (notice the '=' top-level header)
-
Includes all attributes common to OpenShift docs
-
Context used for identifying headers in modules that is the same as the anchor id. Example: cli-developer-commands.
After the heading block and a single whitespace line, you can include any content for this assembly.
|
Note
|
The assembly title, which is the first line of the document, is the only level 1 ( = ) title. Section headers within the assembly must be level 2 ( == ) or lower. When you include modules, you must add leveloffsets in the include statements. You can manually add more level 2 or lower section headers in the assembly. |
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)
[id="<module-anchor>_{context}"] (2)
= Module title (3)
-
List of assemblies in which this module is included.
-
A module anchor with {context} that must match the module’s file name.
-
Human readable title. To ensure consistency in the results of the leveloffset values in include statements, you must use a level one heading ( = ) for the module title.
Example:
// Module included in the following assemblies:
//
// * cli_reference/openshift_cli/developer-cli-commands.adoc
[id="cli-basic-commands_{context}"]
= Basic CLI commands
All headings after the initial title must have a section anchor, with no line spaces between the anchor and the section title and the anchor id should be similar to the section title:
[id="<section-anchor>_{context}"]
=== Section title
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".
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 too long. For assemblies and task modules, use a gerund form in headings, such as:
-
Creating
-
Managing
-
Using
Do not use "Overview" as a heading.
If you have a section heading that you do not want to appear in the TOC (like if you think that some section is not worth showing up or if there are already too many nested levels), you can use a discrete (or floating) heading:
A discrete heading also will not get a section number in the Customer Portal
build of the doc. Previously, we would use plain bold mark-up around a heading
like this, but discrete headings also allow you to ignore section nesting rules
(like jumping from a == section level to a ==== level if you wanted for some
style reason).
To use a discrete heading, just add [discrete] to the line before your unique
ID. For example:
[discrete]
[id="managing-authorization-policies_{context}"]
== Managing authorization policies
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 writing concepts, see the Red Hat modular docs reference guide.
A task contains the steps that users follow to complete a process. Tasks contain ordered steps and explicit commands. In most cases, create your tasks as individual modules and include them in appropriate assemblies.
|
Important
|
Use a verb in the task title (for example, Creating). |
Task modules take the following form:
<module_metadata> After the module file metadata, include a paragraph explaining why the user must perform this task. This should be 1-2 sentences maximum. If applicable, include any gotchas (things that could trip up the user or cause the task to fail). .Prerequisites * A bulleted list of pre-requisites that MUST be performed before the user can complete this task. Skip if there isn't any related information. .Procedure . Step 1 - One command per step. . Step 2 - One command per step. . Step N .Next steps You can explain any other tasks that MUST be completed after this task. You can skip this if there are none. Do not include xrefs. If the next steps are closely related to the task, you might be able to include their modules in the assembly. .Related information * A bulleted list of links to related information about this task. Skip if there isn't any related information.
For more information about writing tasks, see the Red Hat modular docs reference guide.
When possible, generalize references to the product name and/or version using
the {product-title} and/or {product-version} attributes. These attributes
are pulled from 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}.
| Distro | {product-title} |
{product-version} |
|---|---|---|
|
OKD |
1.2, 1.3, 1.4, 1.5, 3.6, 3.7, 3.9, 3.10, 3.11, Latest |
|
OpenShift Container Platform |
3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.9, 3.10, 3.11, 4.1, 4.2 |
|
OpenShift Dedicated |
Latest |
|
OpenShift Online |
Latest |
For example:
You can deploy applications on {product-title}.
This is a safe statement that could appear in probably any of the builds, so an
ifdef/endif
statement is not necessary. For example, if you were viewing a build for the
openshift-enterprise distro (for any of the distro-defined branches), this
would render as:
"You can deploy applications on OpenShift Container Platform."
And for the openshift-origin distro:
"You can deploy applications on OKD."
Considering that we use distinct branches to keep content for product versions
separated, global use of {product-version} across all branches is probably
less useful, but it is available if you come across a requirement for it. Just consider
how it will render across any branches that the content appears in.
If it makes more sense in context to refer to the major version of the product
instead of a specific minor version (for example, if comparing how something in
OpenShift Container Platform 4 differs from OpenShift Container Platform 3),
just use the major version number. Do not prepend with a v, as in v3 or v4.
Do not use markup in headings.
Do not use internal company server names in command or example output. See suggested host name examples here.
Links can be used to cross-reference internal assemblies or send customers to external information resources for further reading.
In OpenShift docs:
-
All links to internal content is created using
xrefand must have an anchor ID. -
Only use
xrefin assemblies, not modules. -
All links to external websites are created using
link.
|
Important
|
Do not split link paths across lines when wrapping text. This will cause issues with the doc builds. |
To provide an example URL path that you do not want to render as a hyperlink, use this format:
`\https://www.example.com`
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. 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 |
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-the-cli[OpenShift CLI]. 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 revert part of an application back to a previous deployment. Rollbacks can be performed using the REST API or the OpenShift CLI.
Before you can create a domain, you must first create an application.
If you want to link to a different website, use:
link:http://othersite.com/otherpath[friendly reference text]
|
Important
|
You must use link: before the start of the URL.
|
|
Important
|
You cannot link to a repository that is hosted on www.github.com. |
|
Tip
|
If you want to build a link from a URL without changing the text from the actual URL, just print the URL without adding a [friendly text] block at the end; it will automatically be rendered as a link.
|
There are two scenarios for linking to other assemblies:
-
Link to another file that exists in the same directory.
-
Link to another file that exists in a separate directory.
The following examples use the example directory structure shown here:
/ /foo /foo/bar.adoc /baz /baz/zig.adoc /baz/zag.adoc
Link to assembly in same directory
xref:<filename>#anchor-id[friendly title]
You must use the .adoc file extension. The document processor will correctly link this to the resulting HTML file.
For example, using the above syntax, if you are working on zig.adoc and want to link to zag.adoc, do it this way:
xref:../zag.adoc#baz-zag[comment]
where baz-zag is the anchor ID at the top of the file zag.adoc.
Link to assembly in different directory
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]
|
Note
|
You must use the .adoc extension in order for the link to work correctly and you must specify an anchor ID. |
To indicate that a feature is in Technology Preview, include the
modules/technology-preview.adoc file in the feature’s assembly to keep the
supportablity wording consistent across Technology Preview features and provide a value for thee :FeatureName: variable before you include this module.
See an example of how this is applied.
To include a block image (an image on its own line):
-
Put the image file in the symlinked
imagesfolder. -
In the
.adoccontent, use this format to link to the image:image::<image_filename>[<alt_text>]
You only have to specify
<image_filename>itself and not the full file path; the build mechanism automatically expands this appropriately.
Inline images can be used to indicate graphic items in the web console, such as
buttons or menu icons. To simplify reuse, the following common SVGs (the
OpenShift web console uses the Font Awesome icon set) have already been added to
the images folder with a user-defined entity added to the
common-attributes.adoc module:
| Icon | Entity | Alt text | File name |
|---|---|---|---|
Kebab |
|
Options menu |
|
When using inline, include the image after the UI element name. For example:
Click the *Options* menu {kebab}.
For all of the system blocks including table delimiters, use four characters. For example:
|=== for tables ---- for code blocks
Code blocks are used to show examples of command screen outputs, or configuration files. When using command blocks, always use the actual values for any items that a user would normally replace. Code blocks should represent exactly what a customer would see on their screen. If you must expand or provide information on what some of the contents of a screen output or configuration file represent, then use callouts to provide that information.
Follow these general guidelines when using code blocks:
-
Do NOT use any markup in code blocks; code blocks generally do not accept any markup.
-
For all code blocks, you must include an empty line above a code block.
Acceptable:
Lorem ipsum ---- $ lorem.sh ----
Not acceptable:
Lorem ipsum ---- $ lorem.sh ----
Without the line spaces, the content is likely to be not parsed correctly.
-
It is recommended to include source tags for the programming language used in the code block to enable syntax highlighting. For example, use the source tags
[source, yaml]or[source, javascript].NoteDo not use [source, bash]foroccommands or any terminal commands, because it does not render properly in some cases.Lorem ipsum ---- $ lorem.sh ----
-
Try to use callouts to provide information on what the output represents when required.
Use this format when embedding callouts into the code block:
---- code example 1 <1> code example 2 <2> ---- <1> A note about the first example value. <2> A note about the second example value.
-
For long lines of code that you want to break up among multiple lines, use a backslash to show the line break. For example:
$ oc get endpoints --all-namespaces --template \ '{{ range .items }}{{ .metadata.namespace }}:{{ .metadata.name }} \ {{ range .subsets }}{{ range .addresses }}{{ .ip }} \ {{ end }}{{ end }}{{ "\n" }}{{ end }}' | awk '/ 172\.30\./ { print $1 }' -
If the user must run a command as root, use a number sign,
#, at the start of the command instead of a dollar sign,$. For example:# subscription-manager list
Do NOT show full commands or command syntax inline within a sentence. The next section covers how to show commands and command syntax.
Only use case for inline commands would be general commands and operations, without replaceables and command options. In this case an inline command is marked up using the back ticks:
Use the `GET` operation to do x.
This renders as:
Use the GET operation to do x.
The main distinction between showing command syntax and example is that a command syntax should just show customers how to use the command without real values. An example on the other hand should show the command with actual values with an example output of that command, where applicable.
To markup command syntax, use the code block and wrap the replaceables in <> with the required command parameters, as shown in the following example. Do NOT use commands or command syntax inline with sentences.
The following command returns a list of objects for the specified object type: ---- $ oc get <object_type> <object_id> ----
This would render as follows:
The following command returns a list of objects for the specified object type:
$ oc get <object_type> <object_id>
As mentioned an example of a command should use actual values and also show an output of the command, as shown in the following example. In some a heading may not be required.
In the following example the `oc get` operation returns a complete list of services that are currently defined. .Example title ---- $ oc get se NAME LABELS SELECTOR IP PORT kubernetes component=apiserver,provider=kubernetes <none> 172.30.17.96 443 kubernetes-ro component=apiserver,provider=kubernetes <none> 172.30.17.77 80 docker-registry <none> name=registrypod 172.30.17.158 5001 ----
This would render as shown:
In the following example the oc get operation returns a complete list of services that are currently defined.
$ oc get se NAME LABELS SELECTOR IP PORT kubernetes component=apiserver,provider=kubernetes <none> 172.30.17.96 443 kubernetes-ro component=apiserver,provider=kubernetes <none> 172.30.17.77 80 docker-registry <none> name=registrypod 172.30.17.158 5001
Lists are created as shown in this example:
. Item 1 (2 spaces between the period and the first character) . Item 2 . Item 3
This will render as such:
-
Item 1
-
Item 2
-
Item 3
If you must add any text, admonitions, or code blocks you have to add the continuous +, as shown in the example:
. Item 1 + ---- some code block ---- . Item 2 . Item 3
This renders as shown:
-
Item 1
some code block
-
Item 2
-
Item 3
| Markup in command syntax | Description | Substitute value in Example block |
|---|---|---|
<username> |
Name of user account |
|
<password> |
User password |
password |
| Markup in command syntax | Description | Substitute value in Example block |
|---|---|---|
<project> |
Name of project |
myproject |
<app> |
Name of an application |
myapp |
Admonitions such as notes and warnings are formatted as shown:
[ADMONITION] ==== Text for admonition ====
Use initial capitalization and camel case for Kubernetes/OpenShift API objects and do not mark them up unless referring to a specific field or variable name from a spec or manifest.
This matches general Kubernetes usage and makes it obvious that a specific concept is being referred to. For example:
-
Pod
-
Deployment
-
Operator
-
DaemonSet (and not "daemon set", "daemonset", or "Daemonset")
An Operator’s full name must be a proper noun, with each word initially capitalized. If it includes a product name, defer the product’s capitalization style guidelines. For example:
-
Cluster Logging Operator
-
Prometheus Operator
-
etcd Operator
-
Node Tuning Operator
-
Cluster Version Operator
| Convention | Markup | Example rendered output |
|---|---|---|
Code blocks |
Use the following syntax for the $ oc <action> <object_type> <object_name_or_id> |
Use the following syntax for the $ oc <action> <object_type> <object_name_or_id> |
Use backticks for all non-GUI "system items", including:
|
`oc get` Set the `upgrade` variable to `true`. Use the `--amend` flag. Answer by typing `Yes` or `No` when prompted. `user_name` `service_name` `package_name` `filename` |
Use the Use the Set the Answer by typing
The |
System or software variable to be replaced by the user |
`<project>` `<deployment>` |
Use the following command to roll back a Deployment, specifying the Deployment name:
|
Use single asterisks for web console / GUI items (menus, buttons, page titles, etc.). Use two characters to form the arrow in a series of menu items, ->. |
Choose *Cluster Console* from the list. Navigate to the *Operators* -> *Catalog Sources* page. Click *Create Subscription*. |
Choose Cluster Console from the list. Navigate to the Operators → Catalog Sources page. Click Create Subscription. |
Use underscores to emphasize the first appearance of a new term. |
An _Operator_ is a method of packaging, deploying, and managing a Kubernetes application. |
An Operator is a method of packaging, deploying, and managing a Kubernetes application. |
Use of single asterisks for general emphasis is allowed but should only be used very sparingly. Let the writing, instead of font usage, create the emphasis wherever possible. |
Do *not* delete the file. |
Do not delete the file. |
Footnotes |
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 Footnotes for the footnote and footnoteref syntax. |