Style and terminology

When writing Kyma documentation, refer to the following guidelines for grammar, capitalization, and preferred word choices. These guidelines help ensure that all contributors write in the same way to ensure a uniform flow throughout the whole Kyma documentation.

TIP: In case of any further doubts concerning the style and standards of writing, see Microsoft Writing Style Guide.

Grammar

These are the generally accepted grammar rules for writing Kyma documentation.

Active voice

Use active voice whenever possible. Active voice is clear, concise, and it avoids misinterpretation. It is also easier for non-native speakers to understand. Passive voice is indirect, uses more words, and can be misleading because it reverses the logical order of events.

βœ… The endpoint path includes your service name.
⛔️ Your service name is to be included in the endpoint path.

Voice and tone

There are different tones for different types of technical documentation, which can range from instructional to somewhat conversational. The goal is always to support people using the product and, in blogs and release notes, also to help business users understand changes.

While writing Kyma documentation, use semi-formal style and imperative mood. The imperative mood tells the reader directly to do something. Use the imperative mood to write instructional documentation such as procedures and tutorials. Other moods can imply optional behavior.

TIP: Consider avoiding click-level instructions. Readers of Kyma documentation are typically fairly tech-savvy.
Avoid using unnecessary words such as "please" or "remember". If there's just one way to do something, don't use "can".

βœ… Save your changes.
βœ… Click Save.
⛔️ Click the Save button.
⛔️ Please, click Save.
⛔️ Remember to click Save.

βœ… Click Upload and select one or more documents.
⛔️ If you want to upload a document, you can click Upload.

Tenses

Use present tense. In technical writing, present tense is easier to read than past or future tense. Simple verbs are easier to read and understand than complex verbs, such as verbs in the progressive or perfect tense. The more concise and straightforward you are, the better.

βœ… If the information does not match, an error message appears.
⛔️ If the information does not match, an error message will appear.

Pronouns

Use the second person and the pronouns "you," "your," and "yours" to speak directly to the reader. Do not use the first person pronouns "we," "us," or "let's."

Contractions

It's okay to use contractions in the documentation from time to time. However, do not overuse it. Otherwise, your text becomes messy and hard to read.

βœ… It's okay to use contractions.
βœ… It is okay to not use them as well.

Articles

Always verify the use of the articles "a", "an", and "the" where appropriate. Use "the" when you refer to a specific example. Use "a" when you refer to something non-specific or hypothetical.

Whenever you refer to the name of our product or one of our components, don't use an article:

βœ… Kyma is awesome.
⛔️ The Kyma is not awesome.

βœ… Application Connector
⛔️ the Application Connector

Punctuation

Use colons and semicolons sparingly. Use the colon ( : ) to introduce a list of things. The semicolon ( ; ) separates two distinct clauses within one sentence. The phrase after a semicolon is a complete sentence. However, the preferred method is without a colon or semicolon.

Use serial commas. A missing serial comma can create confusion about whether the statement applies to each list item individually, or whether the last two items are connected.

βœ… In your request, include the values for the request date, name, and ID.
⛔️ In your request, include the values for the request date, name and ID.

Avoid using parenthesis. Use lists instead, to make your sentences as simple as possible.

βœ… Consider which tasks, such as unit tests, linting, and compilation, are relevant and necessary for your example.
⛔️ The author of each example should consider which tasks (i.e. unit tests, linting and compilation) are relevant and necessary for their example.

Capitalization

Don't capitalize words just because they are "special" or "important".

Whenever you point to the outside sources, research whether the name of the source starts with a capital letter or not.

NOTE: Kubernetes is capitalized. Do not use lowercase or the abbreviation.

βœ… Kubernetes
⛔️ kubernetes
⛔️ k8s

Sentence case

Use Sentence case for:

  • Standard sentences
  • Headings

NOTE: For more details about headings, see the Formatting guidelines.

Title Case

Use Title Case for:

  • The names of Kyma components, such as Application Connector or API Gateway Controller

CamelCase

Use CamelCase for

  • Kubernetes resources
  • custom resources

βœ… API Gateway is a Kubernetes controller, which operates on APIRule custom resources.
⛔️ API Gateway is a Kubernetes controller, which operates on API Rule custom resources.

For plurals, add "s". For titles and navigation, add blank spaces, so that it is natural language instead of camel case.

βœ… ConfigMap, ConfigMaps (resource)
βœ… Config Map, Config Maps (resource in titles and navigation)
⛔️ configmap
⛔️ config map

If you refer to the code specifically, format it as code

NOTE: For more details about code font, see the Formatting guidelines).

βœ… APIRule

If the words are not used in relation to Kubernetes resources, do not capitalize them.

See the following examples of Kubernetes resources:

  • ConfigMap
  • CronJob
  • CustomResourceDefinition (CRD) - note that "custom resource" alone isn't Kubernetes-specific, thus it's lowercase.
  • Deployment
  • Function
  • Ingress
  • Namespace
  • Node
  • PodPreset
  • Pod
  • ProwJob
  • Secret
  • Service
  • ServiceBinding
  • ServiceClass
  • ServiceInstance

Terminology

Use the American English spelling, not British English.

βœ… The color of the message changes from blue to red if there are errors.
⛔️ The colour of the message changes from blue to red if there are errors.

NOTE: Do not use words such as "currently" or "now" to indicate that something is in the transitional phase of development. Avoid promising anything and mention only those components and functionalities that are already in use.

Here is the preferred terminology to use in the Kyma documentation:

βœ… Use⛔️ Don't useComment
API Micro GatewayAPI Gateway
IDid
and+ (plus), & (ampersand)
backendback end, back-end
connect, connectionintegrate, integration
custom resourceCustom Resource, CustomResource
documentdoc
emaile-mail
fill incomplete
frontendfront end, front-end
key-valuekey/value, key:value
micro frontendmicrofrontend, micro front-end
musthave to, need to
needrequire
or/ (slash)
repositoryrepo
runexecute
single sign on (SSO)single sign-on
the following, several,…a specific number
typicallyusually
useutilize
using, withvia
YAML (file format)yamlIf it's a file extension or file name, use .yaml (see formatting)
Prow Job (process)Prowjob, prowjobIf it's a resource, use camel case: "ProwJob"
must, canshouldIf mandatory, use β€œmust”, if optional, use β€œcan”.
(you) canit is possible to, allows you to, there is the possibility to, you have the option to, …If there’s no other option, drop the β€œcan”, simply use imperative.
that isi.e.If you must explain a statement with "i.e." or "that is,…", often the first statement adds little value and can be dropped completely, keeping just the part after "i.e.".
for example, such ase.g.In the middle of a sentence, "such as" is better than "for example". ⛔️ Kyma has many components, for example, Observability, that improve your life.
cloud-native (adjective)cloud nativeRule of thumb: Noun compounds usually don't need a hyphen, adjective compounds often do.
applicationappUse "Application" to describe an external solution connected to Kyma through Application Connector, "application" to describe a microservice deployed on Kyma or other kind of software.
the followingbelow, this, the described, ...or "as shown in the example"
the previous, earlierabove, this, the described, ...or "as shown in the example"

Command line arguments

Use short command line arguments whenever possible.

  • -n, not --namespace

    Short command line arguments can differ between the tools as shown in the following example:

  • Kubernetes: kubectl -n equals kubectl --namespace

  • Helm: helm -n equals helm --name, not helm --namespace

In such a case, explain the context in the document.