Validated Patterns

Contribute to Validated Patterns documentation

Different ways to contribute

There are a few different ways you can contribute to Validated Patterns documentation:

Contribution workflow

When you submit a PR, the Validated Patterns Docs team reviews the PR and arranges further reviews by Quality Engineering (QE), subject matter experts (SMEs), and others, as required. If the PR requires changes, updates, or corrections, the reviewers add comments in the PR. The documentation team merges the PR after you have implemented all feedback, and you have squashed all commits.

Repository organization

├── archetypes
├── content
│   └── blog
|   └── contribute
|   └── learn
|   └── patterns
|       └── multicloud-gitops
|       |   └──_index.adoc
|       |   └──mcg-getting-started.adoc
|       |
|       └── medical-diagnosis
|           └──_index.adoc
|           └── medical-diagnosis-assembly.adoc
├── layouts
│   └── _default
|   └── blog
├── modules
│   └── multicloud-gitops-logical-architecture.adoc
│   └── multicloud-gitops-physical-architecture.adoc
├── static
|   └── images
├── themes/patternfly
├── config.yaml
└── README.adoc

Install and set up the tools and software

Create a GitHub account

Before you can contribute to Validated Patterns documentation, you must sign up for a GitHub account.

Set up authentication

When you have your account set up, follow the instructions to generate and set up SSH keys on GitHub for authentication between your workstation and GitHub.

Confirm authentication is working correctly with the following command:

$ ssh -T git@github.com

Fork and clone the Validated Patterns documentation repository

You must fork and set up the Validated Patterns documentation repository on your workstation so that you can create PRs and contribute. These steps must only be performed during initial setup.

  1. Fork the https://github.com/validatedpatterns/docs repository into your GitHub account from the GitHub UI. Click Fork in the upper right-hand corner.

  2. In the terminal on your workstation, change into the directory where you want to clone the forked repository.

  3. Clone the forked repository onto your workstation with the following command, replacing <user_name> with your actual GitHub username.

    $ git clone git@github.com:<user_name>/docs.git

  4. Change into the directory for the local repository you just cloned.

    $ cd docs

  5. Add an upstream pointer back to the Validated Patterns’s remote repository, in this case docs.

    $ git remote add upstream git@github.com:validatedpatterns/docs.git

This ensures that you are tracking the remote repository to keep your local repository in sync with it.

Install Asciidoctor

The Validated Patterns documentation is created in AsciiDoc language, and is processed with AsciiDoctor, which is an AsciiDoc language processor.

Prerequisites

The following are minimum requirements:

Preview the documentation using a container image

You can use the container image to build the Validated Patterns documentation, locally. To do so, ensure that you have installed the make and podman tools.

  • In the terminal window, navigate to the local instance of the validatedpatterns/docs repository and run the following command:

$ make serve
Verification

A preview is available on your browser at localhost:4000.

Documentation guidelines

Documentation guidelines for contributing to the Validated Patterns Docs

General guidelines

When authoring content, follow these style guides:

Modular documentation terms

Modular doc entityDescription

Asssembly

An assembly is a collection of modules that describes how to accomplish a user story.

Concept module

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.

Procedure module

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".

Reference module

A reference module provides data that users might want to look up, but do not need to remember. A reference module has a very strict structure, often in the form of a list or a table. A well-organized reference module enables users to scan it quickly to find the details they want.

Naming conventions for assembly and module files

Use lowercase separated by dash. Create assembly and module file names that accurately and closely reflect the title of the assembly or module.

Examples

  • designing-guided-decision-tables.adoc (Assembly of guided decision table modules)

  • guided-decision-tables.adoc (Concept module)

  • creating-guided-decision-tables.adoc (Procedure module for creating)

  • guided-decision-table-examples.adoc (Reference module with examples)

Content type attributes

Each .adoc file must contain a :_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:

  • :_content-type: ASSEMBLY

  • :_content-type: CONCEPT

  • :_content-type: PROCEDURE

  • :_content-type: REFERENCE

See, Assembly file metadata and Module file metadata.

Naming conventions for directories

Use lowercase. For directory with a multiple-word name, use lowercase separated by dash, for example multicloud-gitops.

Language and grammar

Consider the following guidelines:

  • Use present tense.

  • Use active voice.

  • Use second person perspective (you).

  • Avoid first person perspective (I, we, us).

  • Be gender neutral.

  • Use the appropriate tone.

  • Write for a global audience.

Titles and headings

Use sentence-style capitalization in all titles and section headings. Ensure that titles focus on customer tasks instead of the product.

For assemblies and procedure modules, use a gerund form in headings, such as:

  • Creating

  • Managing

  • Using

For modules that do not include any procedure, use a noun phrase, for example Red Hat Process Automation Manager API reference.

Writing assemblies

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

Assembly file metadata

Every assembly file should contain the following metadata at the top, with no line spacing in between, except where noted:

:_content-type: ASSEMBLY                                        (1)
[id="<unique-heading-for-assembly>"]                            (2)
= Assembly title                                                (3)
include::_common-docs/common-attributes.adoc[]                  (4)
:context: <unique-context-for-assembly>                         (5)
                                                                (6)
:toc:                                                           (7)
1The content type for the file. For assemblies, always use :_content-type: ASSEMBLY. Place this attribute before the anchor ID or, if present, the conditional that contains the anchor ID.
2A unique anchor ID for this assembly. Use lowercase. Example: cli-developer-commands
3Human readable title (notice the '=' top-level header)
4Includes attributes common to Validated Patterns docs.
5Context used for identifying headers in modules that is the same as the anchor ID. Example: cli-developer-commands.
6A blank line. You must have a blank line here before the toc.
7The table of contents for the current assembly.

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

Writing modules

For more information about creating modules, see the Red Hat Modular documentation reference guide.

Module file metadata

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

// * list of assemblies where this module is included              (1)

:_content-type: <TYPE>                                             (2)
[id="<module-anchor>_{context}"]                                   (3)
= Module title                                                     (4)
1The 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.
2List of assemblies in which this module is included.
3A module anchor with {context} that must be lowercase and must match the module’s file name. The {context} variable must be preceded by an underscore (_) when declared in an anchor ID.
4Human 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/developer-cli-commands.adoc

:_content-type: REFERENCE
[id="cli-basic-commands_{context}"]
= Basic CLI commands

Attribute files

AsciiDoc attributes are variables you can use in common files to:

  • avoid hard-coding brand-specific information,

  • share content between multiple brands more easily.

All attribute files must be placed in the a separate attributes file. For example, common-docs directory.

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

//ACM
rh-rhacm-product: Red Hat Advanced Cluster Management (RHACM)
:rh-shortname: RHACM
//GitOps
:gitops-product: Red Hat OpenShift GitOps
:gitops-shortname: GitOps

For more information on attributes, see link: https://docs.asciidoctor.org/asciidoc/latest/key-concepts/#attributes.

Formatting

Use the following links to refer to AsciiDoc markup and syntax.

If you are graduating to AsciiDoc from Markdown, see the AsciiDoc to Markdown syntax comparison by example.

Formatting commands and code blocks

To enable syntax highlighting, use [source,terminal] for any terminal commands, such as oc commands and their outputs. For example:

[source,terminal]
----
$ oc get nodes
----

To enable syntax highlighting for a programming language, use [source] tags used in the code block. For example:

  • [source,yaml]

  • [source,go]

  • [source,javascript]

QUICKLINKS

CONTRIBUTE

STAY IN TOUCH

Validated Patterns

Validated Patterns are an evolution of how you deploy applications in a hybrid cloud. With a pattern, you can automatically deploy a full application stack through a GitOps-based framework. With this framework, you can create business-centric solutions while maintaining a level of Continuous Integration (CI) over your application.