Writing Guidelines

The Rancher community library contains articles on Rancher products, Kubernetes, container management and orchestration, and related technologies. The following guidelines will help you produce content for our library by matching our style, tone, conventions, and workflow.

To simplify collaboration and publishing, we require article submissions to follow certain general rules.

File Format

Rancher tutorials are written as plain text files using the Markdown markup language. Markdown lets you specify how text should be formatted by including formatting indicators within the text itself. We use a variant of Markdown that includes a few helpful extensions.

When submitting an article for the Rancher library, please contribute it as:

• A plain text document (written in a text editor like Notepad, TextEdit, or Sublime Text instead of a word processor like Word, Google Docs, etc.)
• Formatted in Markdown

You can compare the text documents in the [library repository]() against the versions [rendered on the Rancher website]() to get a better understanding of how formatting is applied. The style and formatting portions of this document will provide additional guidance about how articles are structured.

Article Layout

Follow these guidelines to learn how to compose your Rancher article. Use one of following templates as a starting point for your article:

• Tutorial template
• Comparison template
• Conceptual Template

While the templates demonstrate the basic structure of articles to help you get started, refer to this document for the canonical content guidelines.

Front Matter

Each article should include Hugo front matter at the top of the document to define metadata for the article.

Copy and paste the following template to create a YAML formatted front matter section at the beginning of your article:

---
title: ""
author:
date:
description: ""
type: "blog"
tags: []
categories: [blog]
image: ""
draft: true
---

Fill in the following details:

• title: The title of the article you are publishing, as it should appear on the website.
• author: Your name, with each word separated by a dash (e.g. john-smith). This is used to link your article to your author biography, so use the same string for every article you submit.
• description: A short summary of the article in complete sentences, in 160 characters or less.

Leave the rest of the fields as they are. Your editor on the Rancher team will fill in the remaining information during the publication process.

Section Formatting

Your article should be broken up into sections by using headings. You can further divide logical sections into subsections when sections become long or involve multiple, discrete segments.

• Top-level sections should use two hash marks (##) to define level-two headers.
• Subsections are indicated by an additional hash mark (###) to use a smaller heading than the containing scope.

Only break up a section into two or more subsections. Headings should be progressive, so avoid jumping from a level two heading (##) to a level four heading (####).

Here is an example of an appropriate heading hierarchy:

## Section

### Subsection

### Subsection

## Section

Avoid sections that only contain a single subsection:

## Section

### Subsection

## Section

Avoid skipping heading levels:

## Section

#### Subsection

#### Subsection

## Section

Required Sections

The following sections should be included in every article in the Rancher community.

Introduction

Following the front matter, each article should start off with an introduction. This introduces the topic, outlines the scope of the content, and provides relevant context to help readers understand what the article will be about and how it might help them.

Introductions are typically 1-4 paragraphs long and explain the following:

• What is the article about?
• What will the reader learn by reading and following along?
• Why is this process valuable?
• In what scenarios would this article be most useful?
• Who would benefit from reading this?

An introduction that addresses these types of questions can help readers understand the value of the content and determine if it might be useful for their purposes. If you think that some additional context would be helpful, please include a background section as described below.

(General Sections)

The main body of the article should be comprised of sections that break down the article’s focus into smaller scopes. The section titles and the format will differ depending on the type of article.

For instance, for procedural articles, sections are often split up according to the component being installed and configured, while comparison articles might break down sections based on the different options being evaluated.

Conclusion

The conclusion section should summarize what the article accomplished and what the reader should now understand or be able to do. Final notes or considerations can help users digest what they just read.

Typically, conclusions should contain links to additional resources that the reader can follow to learn more. For conceptual or comparison guides, this might include links to procedural guides to help the user implement the technology discussed. For installation and configuration guides, links to resources that cover usage, etc. can be helpful.

As a general rule, when available, we prefer links to resources within the Rancher community instead of external resources. For external content, we prefer resources from official sources to those from third parties.

Optional or Context-Specific Sections

Some sections may only be appropriate for certain styles of content or for topics that meet certain criteria.

Background or What is X?

Article type: (all)

If additional context would help readers understand the technology you’ll be working with or the processes you will be describing, you can optionally add a background section for further detail. To help keep the article length manageable, when possible, introduce and link out to existing Rancher resources instead of reproducing an explanation.

Prerequisites

Article type: Procedural

The prerequisites section should almost always be included in procedural articles. This section outlines the resources required to successfully follow along with the guide. These should generally be technology requirements like:

• Access to a Linux server with Docker and Rancher installed
• A Google Cloud Platform (GCP) account
• A Docker Hub account
• A Kubernetes cluster deployed on Amazon Web Service’s EKS platform

Prerequisites should usually be provided as a bulleted list. The basic requirement in each bullet should be bolded, with additional context provided after a colon. A relevant link should almost always be included in the bullet’s description to help the reader fulfill the requirement.

For example:

• Access to a Linux server running Rancher: You will need a Linux server to build container images, publish images to Docker Hub, and run a standalone instance of Rancher. Read our quickstart guide to fulfill these requirements by setting up Rancher on a single node.

Goals

Article type: Procedural

If the end goal of a procedural article isn’t immediately apparent in the preceding sections, it may be helpful to include a goals section. This isn’t necessary if the end state is clear from earlier description.

Articles where a goals section might be helpful include:

• Scenarios with many servers in different roles: A goals section can help outline the responsibilities of each machine, the example IP addresses and hostnames we will be using, and the way that they must communicate with one another.
• Complex processes or pipelines: Here, a goals section can be used to discuss how the stages are linked together, the input and output of each phase, and what the full process should produce.
• Article series: The goals section in the first article may include the intended overall outcome of the series. For each subsequent article, the goals section may outline the place that readers should reach by the end of the current article, before proceeding to the next article.

Terminology

Article type: (all)

A terminology section can introduce domain-specific words or phrases that the reader may need to know.

For procedural and comparison guides, this section should mainly focus on terminology that will be used throughout the rest of the guide. Usually, for these guides, you can introduce concepts as you need them without a dedicated section.

For conceptual guides, the terminology section should additionally define any common vocabulary the reader may come across when reading other sources or learning about related topics.

Comparison Framework

Article type: Comparison

For comparison articles, a section that introduces the methodology and framework being used to evaluate different alternatives is often helpful. The comparison framework section covers the criteria being considered during the comparison and may additionally list any characteristics that are not being evaluated in this particular guide.

Conventions

To improve clarity and ensure consistency, Rancher articles follow certain typographical and formatting conventions.

For conventions on commonly used terminology, check out our word usage guide:

• Rancher community word usage guide

Bold

Bold text should be used to emphasize the following elements:

• Important terminology: Emphasize new vocabulary when using them for the first time.
• List items when including a list description: When creating lists that include longer descriptions after each item (like this list), emphasize the list item and separate the item from the description with a colon (:).
• GUI elements like menus, form fields, images, and buttons: This is especially important when instructing readers to interact with or navigate a page. Use the greater than symbol (>) to indicate a sequence of elements. For example: Click on Clusters > My Cluster.
• Keystrokes: Emphasize keys that the user should press. For keys that involve modifier keys, use all capital letters for the modifiers, and join the sequence with a hyphen (-), like CTRL-X.
• Important context changes: When shifting contexts to a different UI, server, account, etc., emphasize the new context to capture attention.

Italics

In general, avoid italics in favor of other methods of emphasizing text. Italics can be difficult to recognize in certain typefaces or sizes.

Inline Highlighting

To bring attention to a specific section of text, use the inline highlighting functionality. You can surround text with {{% hl %}} and {{% /hl %}} to highlight it.

This should primarily be reserved for the following scenarios:

• Variable data: In commands where readers have to substitute their own custom values in a command, highlight and use all caps for the items that should be changed. For example: ssh root@{{% hl %}}RANCHER_SERVER_IP{{% /hl %}} will be rendered as ssh root@RANCHER_SERVER_IP .
• Directing attention in large blocks of text: Highlighting can help users locate information in large amounts of command output, for example.

Inline Code Formatting

Use inline code formatting for the following types of information:

• Command names
• Hostnames
• Usernames
• package names
• file and path names
• URLs that aren’t links (For example, “visit your site’s login page at https://YOUR_SITE /login”)

Notes

Use notes to call attention to blocks of text. Render notes by wrapping text between the {{% note %}} and {{% /note %}} tags. Place notes before any commands they might affect.

For instance, this…:

{{% note %}}
This is a note.
{{% /note %}}

…is rendered as:

Note

This is a note.

Warnings

Use warnings to notify readers of destructive actions or critical information. Place the warning message between the {{% warning %}} and {{% /warning %}} tags. As with notes, place warnings before introducing the operations they might impact.

This warning…:

{{% warning %}}
This is a warning.
{{% /warning %}}

…is rendered like this:

WARNING

This is a warning.

Code Blocks

Use code blocks to render entire blocks of text as preformatted, monospaced text. This is most often used for:

• Code and scripts
• File contents
• Commands and command output
• Interactive textual prompts

You can optionally include a supported language name with the opening code fence to enable syntax highlighting for the block. For instance, opening a code block with ```js indicates that the block should be interpretted and highlighted as Javascript code.

``

Screenshots

Use screenshots to show important visual elements that are not easily represented through text. Screenshots are especially useful in these scenarios:

• Navigating complex web interfaces
• Showing correctly filled out forms
• Demonstrating the final state of a process

When taking screenshots, try to capture helpful surrounding context while maintaining focus on the important elements.

When working with screenshots, follow these rules:

• Screenshots supplement the textual description of the procedure and should never be used as the primary method of documenting a UI or a process
• Always include text before the screenshot to describe the procedure
• Avoid back-to-back screenshots by including descriptions in between each image
• Use screenshots sparingly since they are more difficult to maintain than text.

Diagrams and Other Images

Use diagrams to illustrate relationships, pipelines, workflows, and other complex interactions. Other images can provide context and visualize ideas expressed within the text. Some use cases for diagrams and images include:

• Application and infrastructure architecture
• Process workflow
• Network and process stacks

As with screenshots, images should complement the textual explanation, not replace it.