Skip to content

Commit 815a75d

Browse files
Tim Bannistergraz-devnatalisucksrytswdshannonxtreme
authored and
michellengnx
committed
Add guide to blog contributions
Add a dedicated section about contributing to the Kubernetes official blogs. Co-authored-by: Graziano Casto Co-authored-by: Natali Vlatko Co-authored-by: Ryota Co-authored-by: Shannon Kularathna 
1 parent da94520 commit 815a75d

File tree

16 files changed

+828
-276
lines changed

16 files changed

+828
-276
lines changed

‎content/en/docs/contribute/_index.md

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,16 +14,18 @@ card:
1414
1515

1616
There are lots of ways to contribute to Kubernetes. You can work on designs for new features,
17-
you can document the code we already have, you can write for our [blog](/blog). There's more:
18-
you can implement those new features or fix bugs. You can help people join our contributor
19-
community, or support existing contributors.
17+
you can document the code we already have, you can [write for our blogs](/docs/contribute/blog/).
18+
There's more: you can implement those new features or fix bugs. You can help people join our
19+
contributor community, or support existing contributors.
2020

2121
With all these different ways to make a difference to the project, we - Kubernetes - have made
2222
a dedicated website: https://k8s.dev/. You can go there to learn more about
2323
contributing to Kubernetes.
2424

25-
If you specifically want to learn about contributing to _this_ documentation, read
26-
[Contribute to Kubernetes documentation](/docs/contribute/docs/).
25+
If you specifically want to learn about contributing to the documentation or
26+
other parts of _this_ website, read [Contribute to Kubernetes documentation](/docs/contribute/docs/).
27+
If you specifically want to help with the official Kubernetes blogs, read
28+
[Contributing to Kubernetes blogs](/docs/contribute/blog/).
2729

2830
You can also read the
2931
{{< glossary_tooltip text="CNCF" term_id="cncf" >}}

‎content/en/docs/contribute/blog/_index.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: Contributing to Kubernetes blogs
3+
slug: blog-contribution
4+
content_type: concept
5+
weight: 15
6+
simple_list: true
7+
---
8+
9+
10+
11+
There are two official Kubernetes blogs, and the CNCF has [its own blog](https://www.cncf.io/blog/) where you can cover Kubernetes too.
12+
For the main Kubernetes blog, we (the Kubernetes project) like to publish articles with different perspectives and special focuses, that have a link to Kubernetes.
13+
14+
With only a few special case exceptions, we only publish content that hasn't been submitted or published anywhere else.
15+
16+
Read the [blog guidelines](/docs/contribute/blog/guidelines/#what-we-publish) for more about that aspect.
17+
18+
## Official Kubernetes blogs
19+
20+
### Main blog
21+
22+
The main [Kubernetes blog](/blog/) is used by the project to communicate new features, community reports, and any
23+
news that might be relevant to the Kubernetes community. This includes end users and developers.
24+
Most of the blog's content is about things happening in the core project, but Kubernetes
25+
as a project encourages you to submit about things happening elsewhere in the ecosystem too!
26+
27+
Anyone can write a blog post and submit it for publication. With only a few special case exceptions, we only publish content that hasn't been submitted or published anywhere else.
28+
29+
### Contributor blog
30+
31+
The [Kubernetes contributor blog](https://k8s.dev/blog/) is aimed at an audience of people who
32+
work **on** Kubernetes more than people who work **with** Kubernetes. The Kubernetes project
33+
deliberately publishes some articles to both blogs.
34+
35+
Anyone can write a blog post and submit it for review.
36+
37+
## Article updates and maintenance {#maintenance}
38+
39+
The Kubernetes project does not maintain older articles for its blogs. This means that any
40+
published article more than one year old will normally **not** be eligible for issues or pull
41+
requests that ask for changes. To avoid establishing precedent, even technically correct pull
42+
requests are likely to be rejected.
43+
44+
However, there are exceptions like the following:
45+
46+
* (updates to) articles marked as [evergreen](#maintenance-evergreen)
47+
* removing or correcting articles giving advice that is now wrong and dangerous to follow
48+
* fixes to ensure that an existing article still renders correctly
49+
50+
For any article that is over a year old and not marked as _evergreen_, the website automatically
51+
displays a notice that the content may be stale.
52+
53+
### Evergreen articles {#maintenance-evergreen}
54+
55+
You can mark an article as evergreen by setting `evergreen: true` in the front matter.
56+
57+
We only mark blog articles as maintained (`evergreen: true` in front matter) if the Kubernetes project
58+
can commit to maintaining them indefinitely. Some blog articles absolutely merit this; for example, the release comms team always marks official release announcements as evergreen.
59+
60+
## {{% heading "whatsnext" %}}
61+
62+
* Discover the official blogs:
63+
* [Kubernetes blog](/blog/)
64+
* [Kubernetes contributor blog](https://k8s.dev/blog/)
65+
66+
* Read about [reviewing blog pull requests](/docs/contribute/review/reviewing-prs/#blog)

‎content/en/docs/contribute/blog/buddying.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: Helping as a blog writing buddy
3+
slug: writing-buddy
4+
content_type: concept
5+
weight: 70
6+
---
7+
8+
9+
10+
There are two official Kubernetes blogs, and the CNCF has its own blog where you can cover Kubernetes too.
11+
Read [contributing to Kubernetes blogs](/docs/contribute/blog/) to learn about these two blogs.
12+
13+
When people contributor to either blog as an author, the Kubernetes project pairs up authors
14+
as _writing buddies_. This page explains how to fulfil the buddy role.
15+
16+
You should make sure that you have at least read an outline of [article submission](/docs/contribute/blog/submission/)
17+
before you read on within this page.
18+
19+
20+
21+
## Buddy responsibilities
22+
23+
As a writing buddy, you:
24+
25+
* help the blog team get articles ready to merge and to publish
26+
* support your buddy to produce content that is good to merge
27+
* provide a review on the article that your buddy has written
28+
29+
30+
When the team pairs you up with another author, the idea is that you both support each other by
31+
reviewing the other author's draft article.
32+
Most people reading articles on the Kubernetes blog are not experts; the content should
33+
try to make sense for that audience, or at least to support non-expert readers appropriately.
34+
35+
The blog team are also there to help you both along the journey from draft to publication.
36+
They will either be directly able to approve your article for publication, or can arrange for
37+
the approval to happen.
38+
39+
## Supporting the blog team
40+
41+
Your main responsibility here is to communicate about your capacity, availability and progress
42+
in a reasonable timeline. If many weeks go by and your buddy hasn't heard from you, it makes
43+
the overall work take more time.
44+
45+
## Supporting your buddy
46+
47+
There are two parts to the process
48+
49+
{{< tabs name="buddy_support" >}}
50+
{{% tab name="Collaborative editing" %}}
51+
**(This is the recommended option)**
52+
53+
The blog team recommend that the main author for the article sets up collaborative editing
54+
using either a Google Doc or HackMD (their choice). The main author then shares that document
55+
with the following people:
56+
57+
* Any co-authors
58+
* You (their writing buddy)
59+
* Ideally, with a nominated
60+
person from the blog team.
61+
62+
As a writing buddy, you then read the draft text and either directly make suggestions or provide
63+
feedback in a different way. The author of the blog is very commonly also **your** writing buddy in turn, so they will provide the
64+
same kind of feedback on the draft for your blog article.
65+
66+
Your role here is to recommend the smallest set of changes that will get the article look good
67+
for publication. If there's a diagram that really doesn't make sense, or the writing is really
68+
unclear: provide feedback. If you have a slight different of opinion about wording or punctuation,
69+
skip it. Let the article author(s) write in their own style, provided that they align to
70+
the [blog guidelines](/docs/contribute/blog/guidelines/).
71+
72+
After this is ready, the lead author will open a pull request and use Markdown to submit the
73+
article. You then provide a [review](#pull-request-review).
74+
{{% /tab %}}
75+
{{% tab name="Markdown / Git editing" %}}
76+
Some authors prefer to start with
77+
[collaborative editing](#buddy-support-0); others like to go straight into
78+
GitHub.
79+
80+
Whichever route they take, your role is to provide feedback that lets the blog team provide
81+
a simple signoff and confirm that the article can merge as a draft. See
82+
[submitting articles to Kubernetes blogs](/docs/contribute/blog/submission/) for what the authors
83+
need to do.
84+
85+
Use GitHub suggestions to point out any required changes.
86+
87+
Once the Markdown and other content (such as images) look right, you provide a
88+
formal [review](#pull-request-review).
89+
{{% /tab %}}
90+
{{< /tabs >}}
91+
92+
93+
## Pull request review
94+
95+
Follow the [blog](/docs/contribute/review/reviewing-prs/#blog) section of _Reviewing pull requests_.
96+
97+
When you think that the open blog pull request is good enough to merge, add the `/lgtm` comment to the pull request.
98+
99+
This indicates to the repository automation tooling (Prow) that the content "looks good to me". Prow moves things forward. The `/lgtm` command lets you add your opinion to the record whether or not you are formally a member of the Kubernetes project.
100+
101+
Either you or the article author(s) should let the blog team know that there is an article
102+
ready for signoff. It should already be marked as `draft: true` in the front matter, as
103+
explained in the submission guidance.
104+
105+
## Subsequent steps
106+
107+
For you as a writing buddy, **there is no step four**. Once the pull request is good to merge,
108+
the blog team (or, for the contributor site, the contributor comms team) take things from there.
109+
It's possible that you'll need to return to an earlier step based on feedback, but you can usually expect that your work as a buddy is done.

‎content/en/docs/contribute/blog/guidelines.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: Blog guidelines
3+
content_type: concept
4+
weight: 40
5+
---
6+
7+
8+
9+
These guidelines cover the main Kubernetes blog and the Kubernetes
10+
contributor blog.
11+
12+
All blog content must also adhere to the overall policy in the
13+
[content guide](/docs/contribute/style/content-guide/).
14+
15+
# {{% heading "prerequisites" %}}
16+
17+
Make sure you are familiar with the introduction sections of
18+
[contributing to Kubernetes blogs](/docs/contribute/blog/), not just to learn about
19+
the two official blogs and the differences between them, but also to get an overview
20+
of the process.
21+
22+
## Original content
23+
24+
The Kubernetes project accepts **original content only**, in English.
25+
26+
{{< note >}}
27+
The Kubernetes project cannot accept content for the blog if it has already been submitted
28+
or published outside of the Kubernetes project.
29+
30+
The official blogs are not available as a medium to repurpose existing content from any third
31+
party as new content.
32+
{{< /note >}}
33+
34+
This restriction even carries across to promoting other Linux Foundation and CNCF projects.
35+
Many CNCF projects have their own blog. These are often a better choice for posts about a specific
36+
project, even if that other project is designed specifically to work with Kubernetes (or with Linux,
37+
etc).
38+
39+
## Relevant content
40+
41+
Articles must contain content that applies broadly to the Kubernetes community. For example, a
42+
submission should focus on upstream Kubernetes as opposed to vendor-specific configurations.
43+
For articles submitted to the main blog that are not
44+
[mirror articles](/docs/contribute/blog/mirroring/), hyperlinks in the article should commonly
45+
be to the official Kubernetes documentation. When making external references, links should be
46+
diverse - for example, a submission shouldn't contain only links back to a single company's blog.
47+
48+
The official Kubernetes blogs are **not** the place for vendor pitches or for articles that promote
49+
a specific solution from outside Kubernetes.
50+
51+
Sometimes this is a delicate balance. You can ask in Slack ([#sig-docs-blog](https://kubernetes.slack.com/archives/CJDHVD54J))
52+
for guidance on whether a post is appropriate for the Kubernetes blog and / or contributor blog -
53+
don't hesitate to reach out.
54+
55+
The [content guide](/docs/contribute/style/content-guide/) applies unconditionally to blog articles
56+
and the PRs that add them. Bear in mind that some restrictions in the guide state that they are only relevant to documentation; those marked restrictions don't apply to blog articles.
57+
58+
## Localization
59+
60+
The website is localized into many languages; English is the “upstream” for all the other
61+
localizations. Even if you speak another language and would be happy to provide a localization,
62+
that should be in a separate pull request (see [languages per PR](/docs/contribute/new-content/#languages-per-pr)).
63+
64+
## Copyright and reuse
65+
66+
You must write [original content](#original-content) and you must have permission to license
67+
that content to the Cloud Native Computing Foundation (so that the Kubernetes project can
68+
legally publish it).
69+
This means that not only is direct plagiarism forbidden, you cannot write a blog article if
70+
you don't have permission to meet the CNCF copyright license conditions (for example, if your
71+
employer has a policy about intellectual property that restricts what you are allowed to do).
72+
73+
The [license](https://github.com/kubernetes/website/blob/main/LICENSE) for the blog allows
74+
commercial use of the content for commercial purposes, but not the other way around.
75+
76+
## Special interest groups and working groups
77+
78+
Topics related to participation in or results of Kubernetes SIG activities are always on
79+
topic (see the work in the [Contributor Comms Team](https://github.com/kubernetes/community/blob/master/communication/contributor-comms/blogging-resources/blog-guidelines.md#contributor-comms-blog-guidelines)
80+
for support on these posts).
81+
82+
The project typically [mirrors](/docs/contribute/blog/mirroring/) these articles to both blogs.
83+
84+
85+
## National restrictions on content
86+
87+
The Kubernetes website has an Internet Content Provider (ICP) licence from the government of China. Although it's unlikely to be a problem, Kubernetes cannot publish articles that would be blocked by the Chinese government's official filtering of internet content.
88+
89+
## Blog-specific content guidance {#what-we-publish}
90+
91+
As well as the general [style guide](/docs/contribute/style/style-guide/), blog articles should (not must) align to
92+
the [blog-specific style recommendations](/docs/contribute/blog/article-submission/#article-content).
93+
94+
The remainder of this page is additional guidance; these are not strict rules that articles
95+
must follow, but reviewers are likely to (and should) ask for edits to articles that are
96+
obviously not aligned with the recommendations here.
97+
98+
### Diagrams and illustrations {#illustrations}
99+
100+
For [illustrations](/docs/contribute/blog/article-submission/#illustrations) - including diagrams or charts - use the [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure)
101+
where feasible. You should set an `alt` attribute for accessibility.
102+
103+
Use vector images for illustrations, technical diagrams and similar graphics; SVG format is recommended as a strong preference.
104+
105+
Articles that use raster images for illustrations are more difficult to maintain and in some
106+
cases the blog team may ask authors to revise the article before it could be published.
107+
108+
### Timelessness
109+
110+
Blog posts should aim to be future proof
111+
112+
- Given the development velocity of the project, SIG Docs prefers _timeless_ writing: content that
113+
won't require updates to stay accurate for the reader.
114+
- It can be a better choice to add a tutorial or update official documentation than to write a
115+
high level overview as a blog post.
116+
- Consider concentrating the long technical content as a call to action of the blog post, and
117+
focus on the problem space or why readers should care.
118+
119+
120+
### Content examples
121+
122+
Here are some examples of content that is appropriate for the
123+
[main Kubernetes blog](/docs/contribute/blog/#main-blog):
124+
125+
* Announcements about new Kubernetes capabilities
126+
* Explanations of how to achieve an outcome using Kubernetes; for example, tell us about your
127+
low-toil improvement on the basic idea of a rolling deploy
128+
* Comparisons of several different software options that have a link to Kubernetes and cloud native. It's
129+
OK to have a link to one of these options so long as you fully disclose your conflict of
130+
interest / relationship.
131+
* Stories about problems or incidents, and how you resolved them
132+
* Articles discussing building a cloud native platform for specific use cases
133+
* Your opinion about the good or bad points about Kubernetes
134+
* Announcements and stories about non-core Kubernetes, such as the Gateway API
135+
* [Post-release announcements and updates](#post-release-comms)
136+
* Messages about important Kubernetes security vulnerabilities
137+
* Kubernetes projects updates
138+
* Tutorials and walkthroughs
139+
* Thought leadership around Kubernetes and cloud native
140+
* The components of Kubernetes are purposely modular, so writing about existing integration
141+
points like CNI and CSI are on topic. Provided you don't write a vendor pitch, you can also write
142+
about what is on the other end of these integrations.
143+
144+
145+
Here are some examples of content that is appropriate for the Kubernetes
146+
[contributor blog](/docs/contribute/blog/#contributor-blog):
147+
148+
* articles about how to test your change to Kubernetes code
149+
* content around non-code contribution
150+
* discussions about alpha features where the design is still under discussion
151+
* "Meet the team" articles about working groups, special interest groups, etc.
152+
* a guide about how to write secure code that will become part of Kubernetes itself
153+
* articles about maintainer summits and the outcome of those summits
154+
155+
### Examples of content that wouldn't be accepted {#what-we-do-not-publish}
156+
157+
However, the project will not publish:
158+
159+
* vendor pitches
160+
* an article you've published elsewhere, even if only to your own low-traffic blog
161+
* large chunks of example source code with only a minimal explanation
162+
* updates about an external project that works with our relies on Kubernetes (put those on
163+
the external project's own blog)
164+
* articles about using Kubernetes with a specific cloud provider
165+
* articles that criticise specific people, groups of people, or businesses
166+
* articles that have important technical mistakes or misleading details (for example: if you
167+
recommend turning off an important security control in production clusters, because it can
168+
be inconvenient, the Kubernetes project is likely to reject the article).
169+

0 commit comments

Comments
 (0)