docs: create blog-content-guide.md#2713
Conversation
Signed-off-by: Victoria Nduka <122698422+nwanduka@users.noreply.github.com>
Signed-off-by: Victoria Nduka <122698422+nwanduka@users.noreply.github.com>
juliusv
left a comment
juliusv
left a comment
There was a problem hiding this comment.
Thanks, looks mostly good :) A few comments:
| ## How should posts be written? | ||
|
|
||
| We understand that everyone has their own writing style, and we’d hate to cramp yours. | ||
| So, there are no rigid rules around style. But here a few formatting guidelines to keep the posts consistent: |
There was a problem hiding this comment.
Could you refer to https://github.com/prometheus/docs/blob/main/markdown-guide.md here? That already covers some of the formatting rules.
blog-posts/blog-content-guide.md
Outdated
|
|
||
| We understand that everyone has their own writing style, and we’d hate to cramp yours. | ||
| So, there are no rigid rules around style. But here a few formatting guidelines to keep the posts consistent: | ||
| - **Headings:** Use headings (`#, ##, ###`) to break your post into sections. |
There was a problem hiding this comment.
See https://github.com/prometheus/docs/blob/main/markdown-guide.md#proper-usage-of-heading-levels - the blog post title is already taken from the title frontmatter field, so we want to avoid any explicit H1s in the Markdown content itself.
blog-posts/blog-content-guide.md
Outdated
| We understand that everyone has their own writing style, and we’d hate to cramp yours. | ||
| So, there are no rigid rules around style. But here a few formatting guidelines to keep the posts consistent: | ||
| - **Headings:** Use headings (`#, ##, ###`) to break your post into sections. | ||
| Start with a single `H1` (`#`) for the title, then `H2` for sections and `H3` for subsections. |
blog-posts/blog-content-guide.md
Outdated
|
|
||
| Every post should be reviewed before it goes live. | ||
| One reviewer will look at technical accuracy (usually a maintainer). | ||
| Another (the editor) will focus on readability and style. |
There was a problem hiding this comment.
I think we shouldn't necessarily require more than reviewer, but I guess both roles can be the same person? How about saying that whoever reviews the PR should look out for both the technical and the editorial aspects?
There was a problem hiding this comment.
This makes sense. I've made the adjustment.
|
Sorry, my review backlog is so huge (and increasing) that I cannot review this. I'm sure it's in the best hand with Julius. |
Signed-off-by: Victoria Nduka <122698422+nwanduka@users.noreply.github.com>
juliusv
left a comment
juliusv
left a comment
There was a problem hiding this comment.
Thanks, looking good! Now we just need... BLOG POSTS 🥳😅
|
Amazing! Should we rename this main file to Also it would be epic if this info was somehow rendered in the docs, but it requires some website changes e.g. 
|
@bwplotka Sounds good. I’ll go ahead and make that change. (Update: done that. Link to PR.)
I agree. I think it will make the guide discoverable, but I also recall @juliusv's concern about attracting low-quality “guest posts.” Since the guide itself already sets quality expectations, a low-barrier way to surface it could be to link it from the Contributing section on the Community page (like you suggested earlier). We could consider rendering it directly on the website later if we feel the need, but this seems like a good first step. WDYT? |
4 participants
This PR adds a Blog Content Guide for contributors. The guide is meant to help community members understand what kind of content is a good fit for the Prometheus blog, how to structure posts, and the process for submitting and publishing them.