diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 409f743..4532eb0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,21 +17,54 @@ Thank you for contributing! This blog is a simple, engineer-driven space for tec
## How to contribute a blog post
-1. Announce your blog post idea in the [project](https://github.com/orgs/bbvch/projects/5) with an draft item.
-2. Ready to write? Assign it to yourself and set it in progress
-3. Fork the repo and create a branch (e.g. `blog/my-post-slug`) for your post.
-4. Add yourself as an author in `blog/authors.json` if not already present.
-5. Add a dated folder under `blog/` following the pattern `YYYY-MM-DD-your-slug/`.
- 1. Place the post in `index.md` (or `index.mdx`)
- 2. Include frontmatter (title, description, authors, tags, image) in your post
- 3. Put images in a local `images/` subfolder and reference them relatively (e.g., `./images/cover.png`).
-6. Ready for review/publish?
- 1. Open a Pull Request
- 2. Reference the work item you created in step 1.
- 3. If you want ask somebody for a review.
- 4. CI checks passed?
- 5. Coordinate with maintainers to schedule the publish date (if desired) and merge when ready. As soon as it's merged, it will be live on the blog! No need to wait for a specific publish date.
-7. Congrats, you published your post! Share it widely and engage with readers in the comments.
+### First time contributing?
+
+1. Request to join the [@bbv-blogger team](https://github.com/orgs/bbvch/teams/bbv-blogger) if not already a member.
+2. Clone the repo and setup your local environment. Follow instructions in [README.md](README.md).
+3. [Add yourself as an author](#author-and-tag-registry) in `blog/authors.json` if not already present.
+4. Join our Slack channel #tech-insights-blog
+
+### Publishing workflow
+
+1. Idea for a blog post?
+ 1. Announce your idea in the backlog as a draft item.
+2. Ready to write?
+ 1. Put your draft item in "ready to write"
+ 2. Share your idea with [@bbv-blogger-admin team](https://github.com/orgs/bbvch/teams/bbv-blogger-admin)
+ 3. Find together with [@bbv-blogger-admin team](https://github.com/orgs/bbvch/teams/bbv-blogger-admin) a person who would write a blog on bbv.ch
+ 4. Arrange a date with [@bbv-blogger-admin team](https://github.com/orgs/bbvch/teams/bbv-blogger-admin) (In Roadmap view)
+3. Start with writing
+ 1. Convert to an issue
+ 2. Put it "in progress"
+ 3. Assign it to yourself
+ 4. Create a branch (e.g., `blog/my-post-slug`) for your blog post.
+ 5. Create a [blog post folder structure](#blog-post-folder-structure).
+4. Ready to review?
+ 1. Put it "in review"
+ 2. Create a PR and link to issue with #{issue-number}
+ 3. Request feedback from somebody
+ 4. Update based on feedback where helpful
+5. Ready to publish?
+ 1. Request from [@bbv-blogger-admin team](https://github.com/orgs/bbvch/teams/bbv-blogger-admin) approval in PR
+ 2. When approved, you can merge
+6. Congrats, you published your post!
+ 1. [Share it widely](#cross-posting).
+ 2. Engage with readers in the comments.
+
+### Blog post folder structure
+
+```
+blog/
+ YYYY-MM-DD-your-slug/
+ index.mdx
+ images/
+ cover.png
+ other-image.png
+```
+
+- Each blog post should be in its own folder under `blog/` with a name following the pattern `YYYY-MM-DD-your-slug/`. The date can be the publish date committed with @bbv-blog-admin.
+- `index.mdx` is the main content file for your blog post. It should include [frontmatter](#frontmatter-example) at the top with metadata about the post (title, description, authors, date, tags, image).
+- The `images/` folder is for any images you want to include in your post. You can reference images in your content using relative paths (e.g., `./images/other-image.png`).
### Frontmatter example
@@ -41,19 +74,26 @@ title: "My Post Title"
description: "Short description for the blog list card" # SEO purpose, used in BlogListPage cards
authors:
- autherkey # from blog/authors.yml
-date: 2026-01-21
+date: 2026-01-21 # publish date: use it, if you want to override the date used in the folder name
tags: [tag1, tag2]
-image: ./images/cover.png
+image: ./images/cover.png # relative path to the cover image for this post, used in BlogListPage cards and post page header
---
```
### Cross-posting
-- You can cross-post your content to other platforms, such as LinkedIn, Reddit, Medium, and dev.to. When cross-posting, please link back to the original post on our blog with a canonical URL to drive traffic and engagement.
+- You can cross-post your content to other platforms, such as
+ - LinkedIn,
+ - Reddit,
+ - Medium,
+ - dev.to
+ - and other platforms.
+
+ When cross-posting, please link back to the original post on our blog with a canonical URL to drive traffic and engagement.
- You can cross-post content originally posted on your personal blog here. If you do, please add the following to your blog post (MDX file):
```html
-
+
```
@@ -80,6 +120,6 @@ image: ./images/cover.png
- For help with the publishing workflow, CI, or tooling, contact or tag a maintainer in your PR.
-## Thanks!
+## Thanks
Thank you for contributing. We look forward to your technical content!
diff --git a/README.md b/README.md
index 608fd4f..ae3ef22 100644
--- a/README.md
+++ b/README.md
@@ -2,17 +2,23 @@
A simple, engineer-driven technical blog (Docusaurus) for sharing posts, tutorials, sample code, and videos.
-Quick start
+## Requirements
+
+Install Node.js version 20.0 or above (which can be checked by running node -v). You can use nvm to manage multiple Node.js versions on a single machine.
+When installing Node.js, it is recommended to check all checkboxes related to dependencies.
+See for more details [docusaurus requirements](https://docusaurus.io/docs/installation#requirements)
+
+## Quick start
- Install dependencies: `npm install`
- Run locally: `npm start`
- Build: `npm run build`
-Contributing
+## Contributing
Please read the contribution guidelines: [CONTRIBUTING.md](CONTRIBUTING.md)
-Project structure
+## Project structure
- `blog/` — blog posts and assets (each post in a dated folder)
- `src/` — React components and theme overrides