Skip to content

Commit 5b94b39

Browse files
Copy edit pass on style-guide page (#2120)
Signed-off-by: Nate W <[email protected]>
1 parent a657880 commit 5b94b39

File tree

1 file changed

+34
-34
lines changed

1 file changed

+34
-34
lines changed

content/en/style-guide/_index.md

Lines changed: 34 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ menu:
77
weight: 10
88
---
99

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.
1111

1212
The Cloud Native Glossary follows the [default style guide](https://github.com/cncf/foundation/blob/master/style-guide.md) of the CNCF repository.
1313
Additionally, it follows the following rules:
@@ -25,19 +25,19 @@ Additionally, it follows the following rules:
2525

2626
## Audience
2727

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).
3030

31-
## Minimal Viable Definition
31+
## Minimum viable definition
3232

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.
3434
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 examplesafter all, those things help the reader understand the conceptbut 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 examplesafter all, those things help the reader understand the conceptbut 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.
3838
That part is out of the scope of this Glossary.
3939

40-
## Definition Template
40+
## Definition template
4141

4242
Each glossary term is stored in a markdown file and follows this template:
4343

@@ -72,7 +72,7 @@ title: Definition Template
7272

7373
### Status
7474

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.
7676

7777
Valid values are:
7878

@@ -92,10 +92,10 @@ status: Feedback Appreciated
9292

9393
The **tag** label follows the status label.
9494
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.
9797

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).
9999

100100
The current tags are:
101101

@@ -112,7 +112,7 @@ The current tags are:
112112
---
113113
title: Definition Template
114114
status: Feedback Appreciated
115-
tags: ["tag 1"], ["tag 2"]
115+
tags: ["tag 1", "tag 2", ""]
116116
---
117117
```
118118

@@ -124,21 +124,21 @@ The definitions for **technology** and **concept** categories contain three subh
124124

125125
- **What it is**: provide a short and clear overview of what we are talking about.
126126
- **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.
128128
- **How it helps**: now, come back to the term. How does it address the problem described above?
129129

130130
Note that **properties** don't require separate sections. A definition will suffice.
131131

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.
133133

134134
#### Quality is paramount
135135

136136
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 rushedquality takes time and effort.
137+
Creating a term that meets the CNCF's high standards can't be rushedquality takes time and effort.
138138

139139
**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.
142142
Many definitions are one-sided, especially if provided by a vendor.
143143
The Glossary must contain vendor-neutral, globally accepted definitions.
144144

@@ -151,40 +151,40 @@ Note that we cannot link to content developed by vendors.
151151

152152
#### Keeping it simple
153153

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.
155155
Always keep the audience in mind when drafting your definition.
156-
Avoid using industry terms and buzzwordsyou'll probably catch yourself going back to them and may need to autocorrect.
156+
Avoid using industry terms and buzzwordsyou might catch yourself returning to them and may need to train yourself to look for different terms.
157157

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.
159159

160160
When used in your definition, always **link to existing glossary terms** (only the first mention should be hyperlinked).
161161

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.
164164
Additionally, it uses a real-world example comparing network challenges in a microservices environment (something non-technical people can't relate to)
165165
to wifi problems (something anyone using a laptop can understand).
166166
Where possible, try to make that connection.
167167

168168
#### Start with a Google or Word doc
169169

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.
172172
Also, make sure to run a spellcheck before submitting a PR.
173173

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.
176176

177-
Before getting started, please read some of the published Glossary terms
177+
Before getting started, please read some published Glossary terms
178178
to get a feeling for the level of detail and difficulty and when examples are appropriate.
179179

180-
## The review process: what to expect
180+
## The review process: What to expect
181181

182182
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 timewe 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 timewe appreciate your patience.
184+
If you have any questions, please contact us in the #glossary Slack channel
185185
(for where and how to find it, please refer to our [How To Contribute](/contribute/) doc).
186186

187187
Our goal is for the Glossary to be the best possible resource.
188188
Once you submit a PR, we may ask for one or more revisions.
189-
Don't be frustratedthat 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 frustratedthat 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

Comments
 (0)