Style Guide (Draft)

This page gives writing style guidelines for Rancher documentation. These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document.

Link Syntax

Create links to other files or websites using the following syntax:

[Link Text]({{< baseurl >}})/rancher/v2.x/en/<REMAINING_PATH>

When referencing other Rancher docs, use absolute links instead of relative links, so that if you move either file later, the link still resolve. You can create absolute links by starting the reference path with the {{< baseurl >}} variable.

Do	Don't
[Link Text]({{< baseurl >}})/rancher/v2.x/en/<REMAINING_PATH>	[Link Text](./<RELATIVE_PATH>)

When entering link text, describe the location that the link opens instead of using ambiguous text like "here".

Do	Don't
For more information, see [Dog Breeds].	For more information, go [here].

Images Syntax

Referencing images uses syntax similar to a link, although images begin with !:

![Alt Text]({{< baseurl >}})/img/rancher/<REMAINING_PATH>

Again, the path to your reference should be absolute, not relative.

Do	Don't
/img/rancher/<REMAINING_PATH>	/img/rancher/<RELATIVE_PATH>

Image Directory

When adding images to the docs repo, place them in the docs/src/img/rancher. Don't save your images in the docs/content directory, as this practice can add unwanted links in the doc site's nav structure.

Headings

Use title casing, not sentence casing.

Do	Don't
## Adding Users to Clusters	## Adding users to clusters

Diagrams

TBD.

Doc Repo Directory

The following chart gives a high-level of the doc repo directories you should be concerned with as a contributor.

Note: Ellipsis (...) indicate files and folders in the repo inconsequential for doc writers.

-Docs
    - archetypes    # un-used by content writers
        - ...
    - content
        - os        # source docs for Rancher OS
        - rancher   # source docs for Rancher 2.0
        - rke       # source docs for RKE
    - data          # un-used by content writers
        - ...       
    - layouts
        - ...
        - shortcodes    # contains shortcodes. Includes UI elements and reusable text
    - scripts
        - ...
        - dev           # run to build the doc site on your local host
    - src
        - ...
        - img           # save screencaps and other images referenced in the docs here
    ...

File/Folder Naming Conventions

Folders: all folder names should be lowercase and hyphen delimited.

Do	Don't
/content/rancher/folder-name/	/content/rancher/folderName

Files: all files should be named _index.md.

Moving Documents

The doc site's navigation structure is controlled by doc repo's directory structure. Therefore, when you want to modify the doc site's navigation structure, you'll have need to move documents to a new or existing directory. The nav tree mirrors the directory tree beneath the content directory.

To change the nav structure for the doc site, modify the content directory structure as needed.

Aliases

When you move a document that's previously been published to a new directory, add an alias to the doc's header that points to its old location.

The alias redirects any requests for the document's old location to its new one. This practice prevents 404 errors.

Alias syntax:

When adding aliases, add them to the documents header. Provide the path to the document's old location, starting from the rancher directory, as exemplified below:

---
...
aliases:
  - /rancher/v2.x/en/path/to/old/location/
---

Writing Best Practices

This section has a few rhetoric and grammar tips that can be helpful for writing docs.

Active Versus Passive Voice

In general, sentences written in the active voice are clearer than those written in the passive voice. Prefer using active voice when possible.

Do (use active voice)	Don't (use passive voice)
As you provision a cluster, you can choose cluster options.	When provisioning a cluster, cluster options can be chosen.

Prefer Present Tense

Write your documentation as though someone is using it right now. This practice improves the readability of your docs.

Do	Don't
Click Log in. Rancher opens in your browser.	Click Log in. Rancher will open in your browser.

Avoid Stacking Prepositional Phrases

When technical writing, it's easy to "stack" prepositional phrases consecutively, which makes content more difficult to read. Try not to stack more than two prepositional phrases.

Do	Don't
We have no current estimate of how many boxes of records the school possesses.	There is no current estimate of the number of boxes of records the school possesses.

Addressing the Reader

Address the reader as "you," rather than "the user" or "we". Referring to the reader in the second person helps them understand when their actions are imperative.

Do	Don't
To configure external authentication, you must configure the Rancher options.	To configure external authentication, we must configure the Rancher options. To configure external authentication, the user must configure Rancher options.

Shortcodes

When writing, you can use shortcodes to call on widgets for organizing your docs.

Hugo, the static site generator, ships quite a few shortcodes. We've added a few ourself.

Accordions

Accordions make sections that are collapsible/expandable.

{{% accordion id="uid" label="Section Title" %}}
    content
{{% /accordion %}}

Tabs

Separate information by different tabs.

{{% tabs %}}
   {{% tab "tab one title" %}}
     tab one content
   {{% /tab %}}
   {{% tab "tab two title" %}}
     tab two content
   {{% /tab %}}
 {{% /tabs %}}