-
Notifications
You must be signed in to change notification settings - Fork 118
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: begin official word list for Keptn documentation (#2049)
Signed-off-by: Meg McRoberts <meg.mcroberts@dynatrace.com> Signed-off-by: Moritz Wiesinger <moritz.wiesinger@dynatrace.com> Co-authored-by: Moritz Wiesinger <moritz.wiesinger@dynatrace.com> Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com>
- Loading branch information
1 parent
9616225
commit a656512
Showing
1 changed file
with
78 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,78 @@ | ||
--- | ||
title: Word list | ||
description: Proper use of terms for the Keptn project documentation | ||
weight: 800 | ||
--- | ||
|
||
This document summarizes information | ||
about the proper use of terminology for the Keptn project. | ||
|
||
The Keptn project does not maintain a formal style guide | ||
but should adhere to recommendations in: | ||
|
||
* [CNCF Style Guide](https://github.com/cncf/foundation/blob/main/style-guide.md). | ||
|
||
* The [Kubernetes documentation](https://kubernetes.io/docs/home/) | ||
is a good reference for Kubernetes terms. | ||
In particular: | ||
|
||
* [Concepts](https://kubernetes.io/docs/concepts/) | ||
* [Reference](https://kubernetes.io/docs/reference/) | ||
|
||
* The [Google developer documentation style guide](https://developers.google.com/style) | ||
is a comprehensive reference for technical writers. | ||
In particular: | ||
|
||
* [Word list](https://developers.google.com/style/word-list) | ||
includes good information about words and phrases | ||
that are commonly used in technical documentation | ||
|
||
## Keptn project | ||
|
||
This is the proper name of the project that was developed | ||
under the code name of "Keptn Lifecycle Toolkit (KLT)". | ||
The earlier project is called "Keptn v1". | ||
|
||
* Keptn is capitalized when used in prose as the name of the project, | ||
although the logo uses a lowercase "k". | ||
Use `keptn` if it is part of a command name, pathname, | ||
an argument to a command or function, etc. | ||
|
||
* As a project name that is trademarked, | ||
you should not use an apostrophe-s to make it a possessive ("Keptn's") | ||
or hyphentate it (as in "Keptn-specific"). | ||
|
||
The Keptn project is a "toolkit" with three use cases, named: | ||
|
||
* Metrics (or Deployment data access) | ||
|
||
* Observability (or Deployment observability) | ||
|
||
* Release lifecycle management (or Orchestrate deployment checks) | ||
|
||
## CRD, resource, etc | ||
|
||
Keptn makes extensive use of Kubernetes | ||
[Custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). | ||
It is important to use the related terminology correctly: | ||
|
||
* A "Resource Definition (RD)" is the definition (or syntax) | ||
of a resource that is part of the official Kubernetes API | ||
|
||
* A "Custom Resource Definition (CRD)" is the definition | ||
(or syntax) of a resource that Keptn (or some other product) | ||
adds to Kubernetes | ||
|
||
* An instance of a CRD or RD that a user creates is a custom resource | ||
or just a resource but not a CRD or RD. | ||
Most of the time, we recommend just using the term "resource". | ||
|
||
* The first occurence of a CRD name in a section should be a link to the | ||
[CRD YAML Reference](../../../docs/yaml-crd-ref) | ||
page if there is one. | ||
Otherwise, it should be a link to the appropriate spot in the | ||
[API Reference](../../../docs/crd-ref) | ||
section. | ||
|
||
* Occurrences of a resource name that are not links to a reference page | ||
should be enclosed in tics so they render as code-case. |