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.
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. |
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.
Submariner follows ISO 8601 for date formats (YYYY-MM-DD or YYYY-MM).
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
subctlimage is provided …
Follow the Kubernetes guidelines for writing good release notes.
In particular, note that release notes should be written in past tense.