You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/en/style-guide/_index.md
+34-34Lines changed: 34 additions & 34 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ menu:
7
7
weight: 10
8
8
---
9
9
10
-
This style guide will help you understand the Glossary audience, definition structure, required level of detail, and how to maintain a consistent style.
10
+
This style guide will help you understand the Glossary audience, definition structure, required level of detail, and how to keep a consistent style.
11
11
12
12
The Cloud Native Glossary follows the [default style guide](https://github.com/cncf/foundation/blob/master/style-guide.md) of the CNCF repository.
13
13
Additionally, it follows the following rules:
@@ -25,19 +25,19 @@ Additionally, it follows the following rules:
25
25
26
26
## Audience
27
27
28
-
The Glossary is written for a technical AND non-technical audience.
29
-
Please ensure definitions are explained in simple terms and don’t assume technical knowledge. More do that below under Definition.
28
+
The Glossary is written for technical *and* non-technical audiences.
29
+
Please explain definitions in simple terms, and don’t assume technical knowledge. More about this is below in [Definition](#definition).
30
30
31
-
## Minimal Viable Definition
31
+
## Minimum viable definition
32
32
33
-
Our goal is to make it really easy for anyone to understand cloud native terms.
33
+
We aim to make it easy for anyone to understand cloud native terms.
34
34
As such, we focus on simplicity.
35
-
That means using clear and simple language with examples anyone who uses technology can relate to (more to that below) but also providing a *minimal viable definition*, at least from a technical point of view.
36
-
We don't want to save on context and examples — after all, those things help the reader understand the concept — but if a technical detail is not needed to understand it, we'll skip it.
37
-
The goal is not to overcomplicate things. Once the reader understands the basic concept, other resources will help them dig deeper.
35
+
Use clear, simple language with examples anyone who uses technology can relate to while also providing a *minimum viable definition*, at least from a technical point of view.
36
+
We don't want to save on context and examples—after all, those things help the reader understand the concept—but if a technical detail is not needed to understand it, we'll skip it.
37
+
The goal is not to overcomplicate things. Once the reader understands the basic idea, other resources will help them dig deeper.
38
38
That part is out of the scope of this Glossary.
39
39
40
-
## Definition Template
40
+
## Definition template
41
41
42
42
Each glossary term is stored in a markdown file and follows this template:
43
43
@@ -72,7 +72,7 @@ title: Definition Template
72
72
73
73
### Status
74
74
75
-
The **status** label will come after the title label. The status label indicates whether definitions are thoroughly vetted or require more effort.
75
+
The **status** label will come after the title label. These labels indicate the amount of effort still required to complete the definition.
76
76
77
77
Valid values are:
78
78
@@ -92,10 +92,10 @@ status: Feedback Appreciated
92
92
93
93
The **tag** label follows the status label.
94
94
For the tags to be meaningful and thus helpful to the user, we will use them in a strict sense.
95
-
Applying too many tags will only delute its meaning.
96
-
With the exception of "fundamental," which simply indicates this term is needed to understand other cloud native concepts, most terms will likely only have one tag.
95
+
Applying too many tags will only dilute its meaning.
96
+
An exception to this is the `fundamental` tag, which indicates this term is needed to understand other cloud native concepts; most terms will likely only have one tag.
97
97
98
-
**Note**: Please do not introduce new tags unless approved by the maintainers. When you add tags to an entry, ensure they are spelled exactly as listed below (singular, no typos).
98
+
**Note**: Please only introduce new tags if approved by the maintainers. When you add tags to an entry, ensure they are spelled exactly as listed below (singular, no typos).
99
99
100
100
The current tags are:
101
101
@@ -112,7 +112,7 @@ The current tags are:
112
112
---
113
113
title: Definition Template
114
114
status: Feedback Appreciated
115
-
tags: ["tag 1"], ["tag 2"]
115
+
tags: ["tag 1", "tag 2", ""]
116
116
---
117
117
```
118
118
@@ -124,21 +124,21 @@ The definitions for **technology** and **concept** categories contain three subh
124
124
125
125
-**What it is**: provide a short and clear overview of what we are talking about.
126
126
-**Problem it addresses**: focus on the problem, not the solution (that comes in the next section).
127
-
In fact, avoid mentioning the term that is defined. The problem focuses on *what* led us to need that thing.
127
+
Avoid mentioning the term that is defined. The problem focuses on *what* led us to need that thing.
128
128
-**How it helps**: now, come back to the term. How does it address the problem described above?
129
129
130
130
Note that **properties** don't require separate sections. A definition will suffice.
131
131
132
-
To facilitate review, please use **semantic line breaks** (one sentence per line).
132
+
Please use **semantic line breaks** (one sentence per line) to ease review.
133
133
134
134
#### Quality is paramount
135
135
136
136
If merged, your submission will be the official CNCF definition for that term (until someone else improves it).
137
-
Creating a term that meets the CNCF's high standards can't be rushed — quality takes time and effort.
137
+
Creating a term that meets the CNCF's high standards can't be rushed—quality takes time and effort.
138
138
139
139
**Do your research**: Even if you are confident you know the term, verify you got it right.
140
-
We often use terms in organizations a certain way that may not reflect the full picture.
141
-
When you do your research, especially when you're not 100% familiar with the term, use multiple resources.
140
+
We often use terms in organizations in a certain way that may not reflect the full picture.
141
+
When researching, especially when you're not 100% familiar with the term, use multiple resources.
142
142
Many definitions are one-sided, especially if provided by a vendor.
143
143
The Glossary must contain vendor-neutral, globally accepted definitions.
144
144
@@ -151,40 +151,40 @@ Note that we cannot link to content developed by vendors.
151
151
152
152
#### Keeping it simple
153
153
154
-
The Glossary aims at**explaining complex concepts in simple words** — that is a surprisingly difficult task that will likely take multiple revisions.
154
+
The Glossary aims to**explain complex concepts in simple words**—a surprisingly difficult task that will likely take multiple revisions.
155
155
Always keep the audience in mind when drafting your definition.
156
-
Avoid using industry terms and buzzwords — you'll probably catch yourself going back to them and may need to autocorrect.
156
+
Avoid using industry terms and buzzwords—you might catch yourself returning to them and may need to train yourself to look for different terms.
157
157
158
-
When appropriate, use **real-world examples** that help readers (especially non-technical ones) better understand *when* and *why* the concept you’re explaining is relevant.
158
+
When appropriate, use **real-world examples** that help readers (especially non-technical ones) better understand *when* and *why* the idea you’re explaining is relevant.
159
159
160
160
When used in your definition, always **link to existing glossary terms** (only the first mention should be hyperlinked).
161
161
162
-
**Example**: take a look at the “What it is” section of the [service mesh definition](/service-mesh/).
163
-
It links back to the microservices, service, reliability, and observability definitions.
162
+
**Example**: look at the “What it is” section of the [service mesh definition](/service-mesh/).
163
+
It links back to the definitions of microservices, service, reliability, and observability.
164
164
Additionally, it uses a real-world example comparing network challenges in a microservices environment (something non-technical people can't relate to)
165
165
to wifi problems (something anyone using a laptop can understand).
166
166
Where possible, try to make that connection.
167
167
168
168
#### Start with a Google or Word doc
169
169
170
-
We recommend starting with a Google or Word doc, letting it sit for a few days, and revisiting again.
171
-
This will allow you to catch phrases or expressions that could be worded in a simpler and more accessible way.
170
+
We recommend starting with a Google or Word doc, letting it sit for a few days, and revisiting it.
171
+
This will allow you to catch phrases or expressions that could be worded in a more straightforward and accessible way.
172
172
Also, make sure to run a spellcheck before submitting a PR.
173
173
174
-
To ensure no one else submits a PR while working on a term, make sure to claim an issue (or create one) and that it is assigned to you.
175
-
More to that in the [How To Contribute](/contribute/) doc.
174
+
To ensure no one else submits a PR while working on a term, claim an issue (or create one) and request it be assigned to you.
175
+
More about that in the [How To Contribute](/contribute/) doc.
176
176
177
-
Before getting started, please read some of the published Glossary terms
177
+
Before getting started, please read some published Glossary terms
178
178
to get a feeling for the level of detail and difficulty and when examples are appropriate.
179
179
180
-
## The review process: what to expect
180
+
## The review process: What to expect
181
181
182
182
Please note that we are currently only three maintainers doing this in their spare time.
183
-
Occasionally, we'll be able to review terms quickly; on other occasions, it may take some time — we appreciate your patience.
184
-
If you have any questions, please get in touch with us in the #glossary Slack channel
183
+
Occasionally, we'll be able to review terms quickly; on other occasions, it may take some time—we appreciate your patience.
184
+
If you have any questions, please contact us in the #glossary Slack channel
185
185
(for where and how to find it, please refer to our [How To Contribute](/contribute/) doc).
186
186
187
187
Our goal is for the Glossary to be the best possible resource.
188
188
Once you submit a PR, we may ask for one or more revisions.
189
-
Don't be frustrated — that is the case for many PRs.
190
-
Those backs and forth and our collaboration will ensure that your contribution becomes a truly useful definition read and referred to by readers all around the globe.
189
+
Don't get frustrated—that is the case for many PRs.
190
+
These back and forths and our collaboration will ensure that your contribution becomes a helpful definition read and referred to by readers all around the globe.
0 commit comments