Improve guide to writing blog articles

[sftim]

This is a Feature Request

What would you like to be added

• Based on feedback from people who have written blog articles, improve our guide.

To do this, you would:

• find some people who have written blog articles recently
  • try to pick a mixture of people writing their first article and people who have already contributed to the blog
  • also have a mix of release-related announcements, other project announcements, and articles that are neither
• talk to those people to find out what they found hardest about the process
• based on that feedback, propose one or more pull requests to make the documentation better

Why is this needed

• people writing for our blog find the process hard
• we also have very little blog editorial capacity - see https://github.com/kubernetes/community/blob/master/sig-docs/blog-subproject/README.md (as of 2023-11-28)
  • so it's easier if the articles that come in need less review, and there are fewer round-trips between authors and reviewers

Comments
/sig contributor-experience
/language en

[dipesh-rawat]

I've noticed a couple of additions that could be made to our blog guide based on my reviews of the blog PRs. Contributors could benefit from clearer instructions on incorporating images in blog using Hugo shortcode, addressing issues such as image format and size. Additionally, it would be helpful to include guidance on mirroring blogs between k8s.dev/blog and k8s.io/blog for a smoother overall experience.

[dipesh-rawat]

This would be a valuable enhancement. Improving our guide based on feedback will make the blogging process smoother for contributors and aligns with our goal to streamline reviews. Thanks for raising this @sftim!

/triage accepted
/priority important-longterm
(Please feel free to adjust the priority as needed, if the SIG consensus leans toward a different priority)

[kumarankit999]

Yes @sftim, it would be a great idea. People can write the blog to enhance the kubernetes documentation.

[Rajdeep1311]

Can I submit my blogs? I have recently written 2 blogs, one on my experience in the first ever KubeCon attended and the other on my experience as CNCF zero to merge incubator?

[Gauravpadam]

Sure @Rajdeep1311, We always appreciate blog contributions

(Although this issue is not the correct platform to discuss this)

[Rajdeep1311]

I know that sir, sorry for that but it would be helpful if you could tell me how to contribute to the blog and where can our further discussions take place...I guess Slack? @Gauravpadam

[sftim]

This issue is about explaining how https://kubernetes.io/docs/contribute/new-content/blogs-case-studies/ could be better, and then making those improvements.

@Rajdeep1311 I trust you have read https://kubernetes.io/docs/contribute/new-content/blogs-case-studies/?

[haripriya9647]

@Rajdeep1311 let me know if you are interested in the above issue else I will be happy to work on it.

[Rajdeep1311]

Please, you can work @haripriya9647

[Rajdeep1311]

@haripriya9647 , If you want ma'am we both can work on this

[haripriya9647]

/assign

[Rajdeep1311]

/assign

[haripriya9647]

Hello @sftim
I am planning to work collaboratively with @Rajdeep1311 on this issue. The two of us have decided to create a form that includes all the questions about the blog guides, and based on the response we will be able to identify the pain points and analyze appropriate solutions.
As soon as the form has been created, we will head to the sig-docs-blog slack channel to gather a list of recent contributors from different domains, and we will contact them and ask them to fill out the form, as well as posting the form in blog-related channels.

[Rajdeep1311]

Any replies @sftim sir?

[sftim]

I am planning to work collaboratively with @Rajdeep1311 on this issue. The two of us have decided to create a form that includes all the questions about the blog guides, and based on the response we will be able to identify the pain points and analyze appropriate solutions.
As soon as the form has been created, we will head to the sig-docs-blog slack channel to gather a list of recent contributors from different domains, and we will contact them and ask them to fill out the form, as well as posting the form in blog-related channels.

That sounds fine.

I think @david-martin has also made a start here.

[david-martin]

Some updates on this.

using Hugo shortcode

#44967

clearer instructions on incorporating images in blog
addressing issues such as image format and size.

There is a diagram guide already at https://kubernetes.io/docs/contribute/style/diagram-guide/

@dipesh-rawat Is there something specific missing from that, or is the discoverability of that page a problem when writing blogs?

I did get some specific suggestions from @sftim, which we can add to that diagram guide if it makes sense and isn't sufficiently covered already:

• PNG with alpha for anything that has a shape, like a logo, and doesn't have a vector version
• JPEG for photos, either original size or scaled down to 1920px maximum dimension
  We can use optimization tools suitable to the format if images seem particularly large.

Also, regarding:

mirroring blogs between k8s.dev/blog and k8s.io/blog

I'm not familiar with the process here, but a suggestion was to write a blog article on how to do this and publish it.
@dipesh-rawat Is there someone you'd recommend reaching out to that has this knowledge, and when to use 1 vs. the other, and when you'd consider mirroring?

[david-martin]

mirroring blogs between k8s.dev/blog and k8s.io/blog

@Gauravpadam Perhaps this is something you have some notes about?
I see you added #44722 to mirror kubernetes/contributor-site#424

[Gauravpadam]

Sure @david-martin, I'll be glad to help with the process. I'll reach out to you on slack.

[a-mccarthy]

Hello, reaching out to see what the current state of this issue is? I was thinking of ways we could ask for feedback from release feature blog authors (current cycle 1.31), so maybe we can combine efforts?

[david-martin]

@a-mccarthy I know there were a few small updates to the docs around contributing. In that sense, improvements were made.

find some people who have written blog articles recently ... talk to those people ... based on that feedback, propose one or more pull requests

However, I'm not aware of what has progressed in this area.
This comment from @haripriya9647 (with @Rajdeep1311 mentioned) suggested a form was being created to gather feedback from blog authors. I would defer to either of them on how that has progressed.