Docs Style Guide

Documentation Style Guide

This guide is meant to help keep our documentation consistent and ease the contribution and review process.

Submariner follows the Kubernetes Documentation Style Guide wherever relevant. This is a Submariner-specific extension of those practices. Word List

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

Term Usage
Admiral The project name Admiral should always be capitalized.
Broker The design pattern component Broker should always be capitalized.
ClusterSet The Kubernetes object ClusterSet proposed in KEP1645 should always be CamelCase and formatted in code style.
Cluster set The words “cluster set” should be used as a term for a group of clusters, but not the proposed Kubernetes object.
Coastguard The project name Coastguard should always be capitalized.
Globalnet The feature name Globalnet is one word, and so should always be capitalized and should have a lowercase “n”.
IPsec The protocol IPsec should follow the capitalization used by RFCs and popular sources.
iptables The application iptables consistently uses all-lowercase. Follow their convention, but avoid starting a sentence with “iptables”.
K8s The project nickname K8s should typically be expanded to “Kubernetes”.
kind The tool kind consistently uses all-lowercase. Follow their convention, but avoid starting a sentence with “kind”.
Lighthouse The project name Lighthouse should always be capitalized.
Operator The design pattern Operator should always be capitalized.
OpenStack The project name OpenStack should always be capitalized and camel-cased.
Shipyard The project name Shipyard should always be capitalized.
subctl The artifact subctl should not be capitalized and should be formatted in code style.
Submariner The project name Submariner should always be capitalized.
VXLAN The protocol VXLAN should always be all-capitalized.

Pronunciation of “Submariner”

Both the “Sub-mariner” (“Sub-MARE-en-er”, like the watch) and “Submarine-er” (“Sub-muh-REEN-er”, like the Navy job) pronunciations are okay.

The second option, “Submarine-er”, has historically been more common as Chris Kim (the initial creator) imagined the iconography of the project as related to submarine cables.

Date Format

Submariner follows ISO 8601 for date formats (YYYY-MM-DD or YYYY-MM).

Use Versions, not “New”

Avoid referring to things as “new”, as this will become out of date and require maintenance. Instead, document the versions that introduce or remove features:

As of 0.12.0, a subctl image is provided …

Release Notes Formatting

Follow the Kubernetes guidelines for writing good release notes.

In particular, note that release notes should be written in past tense.