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.
|Admiral||The project name Admiral should always be capitalized.|
|Broker||The design pattern component Broker should always be capitalized.|
||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.|
|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.