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/docs/content/style-guide/_index.md
+43-70
Original file line number
Diff line number
Diff line change
@@ -5,47 +5,29 @@ description: >
5
5
things content.
6
6
classification: public
7
7
---
8
-
9
-
Writing isn’t a test. Even if you ignore all these guidelines, that’s okay — that’s what good editing is all about. It should help you, not hamper your creativity. So write how you feel and SIG Content ([#sig-content](https://gigantic.slack.com/archives/C02NGJTJN)) + SIG Docs ([#sig-docs](https://gigantic.slack.com/archives/C03FYAV8U)) will be there to support, shape your ideas, answer questions and review your content.
8
+
Writing isn’t a test. Even if you ignore all these guidelines, that’s okay — that’s what good editing is all about. It should help you, not hamper your creativity. So write how you feel, and SIG Content (#sig-content) + SIG Docs (#sig-docs) will be there to support and shape your ideas, answer questions and review your content.
10
9
11
10
In this article, you find guidelines around goals, voice and grammar, the basic knowledge for writing content. For more specific information, please also read our [blog content guide](https://intranet.giantswarm.io/docs/content/blog-content-guide/) or [social media guide](https://intranet.giantswarm.io/docs/content/social-media-guide/).
12
11
13
12
14
13
15
14
## How we want to sound
16
15
17
-
-**Be conversational**
18
-
19
-
This isn’t an essay you’ll be graded on. Write how you speak, encourage a two-way conversation.
20
-
21
-
-**Let the reader be a bit lazy**
22
-
23
-
Get to the point and let the article be digestible. This is true for word choice and formatting.
24
-
25
-
-**Show your personality**
26
-
27
-
If you have fun while writing it, the reader will likely have fun while reading it.
28
-
29
-
-**Think about the finished product**
30
-
31
-
Add pictures, diagrams, memes… Think about what someone would tweet about if they read your article.
32
-
33
-
-**Be generous with knowledge**
34
-
35
-
If there’s a helpful link, include it. If you can add a summary (TL;DR), do. We’re not possessive about our knowledge because we have a lot of it.
36
-
37
-
-**Be nice**
38
-
39
-
Write how you would like to be written to. Be cool.
16
+
-**Be conversational:** This isn’t an essay you’ll be graded on. Write how you speak, encourage a two-way conversation.
17
+
-**Let the reader be a bit lazy:** Get to the point and let the article be digestible. This is true for word choice and formatting.
18
+
-**Show your personality**: If you have fun while writing it, the reader will likely have fun while reading it.
19
+
-**Think about the finished product**: Add pictures, diagrams, memes… Think about what someone would tweet about if they read your article.
20
+
-**Be generous with knowledge:** If there’s a helpful link, include it. If you can add a summary (TL;DR), do. We’re not possessive about our knowledge because we have a lot of it.
21
+
-**Be nice:** Write how you would like to be written to. Be cool.
40
22
41
23
## Goals
42
24
43
25
While these aren’t exhaustive, with every piece of content, we aim to:
44
26
45
-
-**Educate**Share knowledge on the things we care about.
-**Share our values**: Our values should be reflected in all that we do.
30
+
-**Share what makes us special**: We’re in the best position to share what makes us unique; let’s remember to do just that.
49
31
50
32
## Voice
51
33
@@ -60,9 +42,8 @@ Here are some Dos and Don'ts for you to consider:
60
42
- Don’t be formal, write like a person. Write as you would speak to a friend.
61
43
- Where relevant, start sentences with verbs to keep things punchy.
62
44
63
-
> ✔️ Write punchy content by keeping sentences short.
64
-
65
-
> ❌ The way to write punchy content is by keeping sentences short.
45
+
> ✔️ Write punchy content by keeping sentences short.
46
+
> ❌ The way to write punchy content is by keeping sentences short.
66
47
67
48
- Say it simply or don’t say it at all — unless it’s really funny, then that’s okay. If it confuses you a little, it’s going to confuse us a lot.
68
49
- Don’t write like a robot, put your heart into it.
@@ -73,52 +54,42 @@ Here are some Dos and Don'ts for you to consider:
73
54
74
55
- Friendly details count. Use contractions:
75
56
76
-
> ✔️ it’s
77
-
78
-
> ❌ it is
79
-
80
-
> ✔️ you’re
81
-
82
-
> ❌ you are
83
-
84
-
> ✔️ we’re
85
-
86
-
> ❌ we are
87
-
88
-
> ✔️ let’s
89
-
90
-
> ❌ let us
57
+
> ✔️ it’s
58
+
> ❌ it is
59
+
> ✔️ you’re
60
+
> ❌ you are
61
+
> ✔️ we’re
62
+
> ❌ we are
63
+
> ✔️ let’s
64
+
> ❌ let us
91
65
92
66
- We are firm believers in the Oxford comma: in a list of three or more items, include a comma before the conjunction. 🇬🇧
93
67
94
-
> ✔️ These are the options you have for defining the size of a Kubernetes cluster, choosing the instance types, and automatically scaling the cluster.
95
-
96
-
> ❌ These are the options you have for defining the size of a Kubernetes cluster, choosing the instance types and automatically scaling the cluster.
68
+
> ✔️ These are the options you have for defining the size of a Kubernetes cluster, choosing the instance types, and automatically scaling the cluster.
69
+
> ❌ These are the options you have for defining the size of a Kubernetes cluster, choosing the instance types and automatically scaling the cluster.
97
70
98
71
- Other than that, Giant Swarm uses American English across all platforms. 🇺🇸
99
72
100
-
> ✔️ center
101
-
102
-
> ❌ centre
73
+
> ✔️ center
74
+
> ❌ centre
103
75
104
76
- Spell out numbers one to ten and use the numerals for the rest.
105
77
- Don’t use ellipses (`…`) for drama or emphasis but only to indicate trailing off and only then sparingly. Or used in a bracket to indicate that you’re omitting words from a quote. “She loves working Monday to Friday [...] her boss is reading.”
106
78
107
79
### Capitalization
108
80
109
-
This applies to Giant Swarm text on the blog, website, public and internal documentation, and social media. Visual assets are excluded from this rule – they may use [title case](https://en.wikipedia.org/wiki/Title_case)).
81
+
This applies to the Giant Swarm text on the blog, website, public and internal documentation, and social media. Visual assets are excluded from this rule – they may use [title case](https://en.wikipedia.org/wiki/Title_case)).
110
82
111
83
To ensure consistency, use sentence-case capitalization. This means capitalizing only the first word of a sentence (excluding proper nouns, brands, services).
112
84
113
85
- If a sentence begins with a lowercase word, rewrite this sentence if possible.
114
86
115
-
> ✔️ Not many people know that adidas is lowercase.
116
-
117
-
> ❌ adidas is lowercase can you believe it.
87
+
> ✔️ Not many people know that adidas is lowercase.
88
+
> ❌ adidas is lowercase can you believe it.
118
89
119
90
- Don’t use internal capitalization
120
91
121
-
> ❌ e-Commerce
92
+
> ❌ e-Commerce
122
93
123
94
- When spelling out acronyms, only capitalize if it’s a proper noun.
124
95
- If using a slash, for example `On/Off`, always make the words match: lowercase/lowercase or Uppercase/Uppercase.
@@ -138,18 +109,20 @@ These are words we try to avoid because they’re clichéd, jargon-y or overly c
- Check out the [technical writing session](https://drive.google.com/file/d/18vhM3PHwNW4zhh4nDSVqG8hXdHycd8aW/view?usp=sharing) hosted by Andreas Sommer [2024/03/14]
126
+
- Read through the [Google Tech Writing training](https://developers.google.com/tech-writing/one/summary).
127
+
- Check out the [technical writing session](https://drive.google.com/file/d/18vhM3PHwNW4zhh4nDSVqG8hXdHycd8aW/view?usp=sharing) hosted by Andreas Sommer [2024/03/14].
0 commit comments