This style guide is adapted from the Kubernetes style guide.

This page outlines writing style guidelines for the Harbor documentation and you should use it as a reference as you write or edit content. These are guidelines, not rules. Use your best judgment as you write documentation, and feel free to propose changes to these guidelines.

Changes to the style guide are made by the Harbor maintainers as a group. To propose a change or addition create an issue/PR, or come to a community meeting to discuss your suggestions.

The Harbor documentation uses the Goldmark Markdown renderer.

Content best practices

Use present tense

Exception: Use future or past tense if it is required to convey the correct meaning.

Use active voice

Exception: Use passive voice if active voice leads to an awkward sentence construction.

Use simple and direct language

Use simple and direct language. Avoid using unnecessary phrases, such as saying “please.”

Address the reader as “you”

Avoid Latin phrases

Prefer English terms over Latin abbreviations.

Exception: Use “etc.” for et cetera.

Patterns to avoid

Avoid using “we”

Using “we” in a sentence can be confusing, because the reader might not know whether they’re part of the “we” you’re describing.

Avoid jargon and idioms

Many readers speak English as a second language. Avoid jargon and idioms to help them understand better.

Avoid statements about the future or that will soon be out of date

Avoid making promises or giving hints about the future. If you need to talk about a beta feature, put the text under a heading that identifies it as beta information.

Also avoid words like “recently”, “currently” and “new.” A feature that is new today might not be considered new in a few months.

Language

This documentation uses U.S. English spelling and grammar.

Documentation formatting standards

Use angle brackets for placeholders

Use angle brackets for placeholders. Tell the reader what a placeholder represents.

1. Display information about a Pod:

    kubectl describe pod <pod-name> -n <namespace>

   If the pod is in the default namespace, you can omit the ‘-n’ parameter.

Use bold for user interface elements

Use code style for filenames, directories, paths, object field names and namespaces

Use punctuation inside quotes

Exception: When the quoted word is a user input.

Example:

• My user ID is “IM47g”.
• Did you try the password “mycatisawesome”?

Inline code formatting

Use code style for inline code and commands

For inline code in an HTML document, use the <code> tag. In a Markdown document, use the backtick (` ).

Use normal style for string and integer field values

For field values of type string or integer, use normal style without quotation marks.

Code snippet formatting

Don’t include the command prompt

Separate commands from output

Verify that the Pod is running on your chosen node:

kubectl get pods --output=wide

The output is similar to this:

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Harbor word list

A list of Harbor-specific terms and words to be used consistently across the site.

Markdown elements

Headings

People accessing this documentation may use a screen reader or other assistive technology (AT). Screen readers are linear output devices, they output items on a page one at a time. If there is a lot of content on a page, you can use headings to give the page an internal structure. A good page structure helps all readers to easily navigate the page or filter topics of interest.

Paragraphs

Links

Lists

Group items in a list that are related to each other and need to appear in a specific order or to indicate a correlation between multiple items. When a screen reader comes across a list—whether it is an ordered or unordered list—it will be announced to the user that there is a group of list items. The user can then use the arrow keys to move up and down between the various items in the list. Website navigation links can also be marked up as list items; after all they are nothing but a group of related links.

• End each item in a list with a period if one or more items in the list are complete sentences. For the sake of consistency, normally either all items or none should be complete sentences.

• Ordered lists that are part of an incomplete introductory sentence can be in lowercase and punctuated as if each item was a part of the introductory sentence.

• Use the number one (1.) for ordered lists.

• Use (+), (*), or (-) for unordered lists - be consistent within the same document.

• Leave a blank line after each list.

• Indent nested lists with four spaces (for example, ⋅⋅⋅⋅).

• List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either four spaces or one tab.

Tables

The semantic purpose of a data table is to present tabular data. Sighted users can quickly scan the table but a screen reader goes through line by line. A table caption is used to create a descriptive title for a data table. Assistive technologies (AT) use the HTML table caption element to identify the table contents to the user within the page structure.

If you need to create a table, create the table in markdown and use the table Hugo shortcode to include a caption.

{{< table caption="Configuration parameters" >}}
Parameter | Description | Default
:---------|:------------|:-------
`timeout` | The timeout for requests | `30s`
`logLevel` | The log level for log output | `INFO`
{{< /table >}}

Note: This shortcode does not support markdown reference-style links. Use inline-style links in tables. See more information about markdown link styles.