docs: improve CONTRIBUTING.md #327

iambel · 2025-05-06T17:56:25Z

reorganized and emphasized key sections in CONTRIBUTING.md to improve clarity and guidance for new contributors

reorganized and emphasized key sections in CONTRIBUTING.md to improve clarity and guidance for new contributors

karasowles

Thanks for adding some clarity here and streamlining it!

I'd like to keep the "title: 'Your Event Title' etc. sample code, rather than put the Africa example back in. It's been easier to copy-paste and fill in.

Let's also keep the Content Guidelines at the bottom, for thoroughness.

correcting some details based on feedback received

iambel · 2025-05-06T23:46:10Z

i noticed what was missing and submitted a pull request with changes based on your feedback (thanks!). let me know if there’s anything else you would like me to adjust

adiati98

Hey @iambel,
You made such a great start here! ✨

I left some comments here for my thoughts and ideas. However, please note that I'm not a maintainer of this repo. So, all decisions will go to the maintainers. 👍🏼

Other than these comments, I also have some thoughts in general.

I see there are many icons here. The titles also have an icon. I'm not sure if a guide should have icons for titles, but if this is what the maintainers want, then let's go with it. 🙂
There are many bold sentences. Highlighting things important with bold fonts are great, but when there are too many, I think it would make folks to pay more attention to the bold ones and screen the whole guide rather than reading it thoroughly.

cc: @karasowles

adiati98 · 2025-05-07T13:15:47Z

CONTRIBUTING.md

@@ -1,30 +1,54 @@
 # Contributing to GitHub Maintainer Month

-:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
+### Hey there! 👋


suggestions: Markdown best practice and accessibility wise, there should be an H2 before H3 after the H1. Is the reason for applying H3 here because of the font size? Because we better make this an H2 or part of the paragraph instead.

adiati98 · 2025-05-07T13:19:05Z

CONTRIBUTING.md

-## Quick Navigation
+This document provides **guidelines** and **instructions** for contributing to the **Maintainer Month** website.
+
+🎇 Don't worry if you're new here, we appreciate supporting and giving chances for **first-time contributions**! If you have any questions, **feel free to reach out for help** and we'll try to answer as soon as possible! 💚🚀


questions: I believe we want to encourage first-time contributor with this sentence? However, I get the impression that we only receiving first-time contribution. Or is this the intention?

suggestion: We might want to reword this to welcoming all contributors (first timer and regular) if that's the goal.

adiati98 · 2025-05-07T13:23:33Z

CONTRIBUTING.md


-The Maintainer Month website is maintained by the Open Source team at GitHub. You can reach out at <maintainermonth @ github .com>
+The **Maintainer Month** website is maintained by the **Open Source team at GitHub**. You can reach out at <maintainermonth@github.com> 💚


@karasowles now there is a CODEOWNERS file. Do you want folks to reach out to the email for questions and all, or tag the maintainers that are listed in the CODEOWNERS?

adiati98 · 2025-05-07T13:26:22Z

CONTRIBUTING.md


-> **Important:** Do not modify variable names in frontmatter sections (between `---`). These are required for the website to function properly.
+> **📌 Important:** Do not modify variable names in frontmatter sections (between `---`). These are required for the website to function properly.


suggestions: Maybe we can utilize the GitHub admonition here.

Suggested change

> **📌 Important:** Do not modify variable names in frontmatter sections (between `---`). These are required for the website to function properly.

> [!IMPORTANT]

> Do not modify variable names in frontmatter sections (between `---`). These are required for the website to function properly.

adiati98 · 2025-05-07T13:30:39Z

CONTRIBUTING.md


 1. Clone the repository
+
+```bash
+git clone https://github.com/iambel/maintainermonth.git


suggestion: I believe we want this guide to be general and easier to understand. So, let's do GitHub's template (refer to the step 6) here.

Suggested change

git clone https://github.com/iambel/maintainermonth.git

git clone https://github.com/YOUR-USERNAME/maintainermonth.git

iambel · 2025-05-12T16:57:14Z

hey!
i reviewed all the feedback and pushed a new commit with some corrections. it should be cleaner now

iambel · 2025-05-19T14:04:49Z

hi! just following up on this PR. let me know if there's anything i should improve or clarify. 👐

adiati98

Hey @iambel,

I left some reviews here.
As for content matters, I leave it to the maintainers to review them. 👍🏼

adiati98 · 2025-05-19T15:00:03Z

CONTRIBUTING.md

+  - [Adding a New Resource
+    ](#adding-a-new-resource)


The closing bracket should be inline.

Suggested change

- [Adding a New Resource

](#adding-a-new-resource)

- [Adding a New Resource](#adding-a-new-resource)

adiati98 · 2025-05-19T15:00:23Z

CONTRIBUTING.md

+  - [Making Code Changes
+    ](#making-code-changes)


Suggested change

- [Making Code Changes

](#making-code-changes)

- [Making Code Changes](#making-code-changes)

adiati98 · 2025-05-19T15:00:40Z

CONTRIBUTING.md

+  - [Setting Up Your Environment
+    ](#setting-up-your-enviroment)


Suggested change

- [Setting Up Your Environment

](#setting-up-your-enviroment)

- [Setting Up Your Environment](#setting-up-your-enviroment)

adiati98 · 2025-05-19T15:01:46Z

CONTRIBUTING.md


 ## Contribution Walkthrough

-### Adding a New Event
+### → Adding a New Event


As there is no icon for the titles anymore, let's remove this one as well.

Suggested change

### → Adding a New Event

### Adding a New Event

adiati98 · 2025-05-19T15:04:47Z

CONTRIBUTING.md

+If you want to add a new event, go to the `content/events/` folder.

-1. Navigate to the `content/events/` folder
-2. Create a new markdown file with a descriptive name (e.g., `2025-05-20-your-event-name.md`)
-3. Use the following template:
+Each event is documented in a markdown file for each one. So, to create one:
+
+2. Create a new markdown file with a descriptive name (e.g., `2025-05-20-your-event-name.md` )
+3. Use the following template to add the event details:


Thoughts: I think we can stick to the original instructions here. But maintainers are the best to decide.

1. Navigate to the `content/events/` folder 2. Create a new markdown file with a descriptive name (e.g., `2025-05-20-your-event-name.md`) 3. Use the following template: ...

adiati98 · 2025-05-19T15:21:13Z

CONTRIBUTING.md

-### Frontmatter Fields
+Here you’ll find explanations and instructions for filling out content templates. Following these guidelines helps keep everything organized and easy to review!
+
+## → Frontmatter Fields


This is part of "Content Guidelines" section. So, it should be an H3.

Suggested change

## → Frontmatter Fields

### Frontmatter Fields

adiati98 · 2025-05-19T15:22:34Z

CONTRIBUTING.md


-#### Event Fields
+## → Event Fields


This is part of "Frontmatter Fields". Therefore, it should be an H4.

Suggested change

## → Event Fields

#### Event Fields

adiati98 · 2025-05-19T15:23:20Z

CONTRIBUTING.md

@@ -123,7 +164,7 @@ Detailed description of your event goes here. You can use markdown formatting.
 - `userLink`: Link to organizer profile/website
 - `linkUrl`: Direct link to the event

-#### Library Resource Fields
+## → Library Resource Fields


Suggested change

## → Library Resource Fields

#### Library Resource Fields

adiati98 · 2025-05-19T15:24:23Z

CONTRIBUTING.md

@@ -132,7 +173,7 @@ Detailed description of your event goes here. You can use markdown formatting.
 - `type`: Content type (e.g., `video`, `article`, `tutorial`)
 - `topics`: Relevant topic tags

-### Static Content
+## → Static Content


This is part of "Content Guidelines". So, it should be an H3.

Suggested change

## → Static Content

### Static Content

adiati98 · 2025-05-19T15:29:16Z

CONTRIBUTING.md

@@ -141,6 +182,6 @@ Other content files are organized as follows:

 When editing these files, maintain the existing structure and frontmatter fields.

-### Questions?
+## Questions


Let's put back the questions mark here. Without one, it feels like we are the one who have questions for folks.

Suggested change

## Questions

## Questions?

docs: improve CONTRIBUTING.md

5ca0173

reorganized and emphasized key sections in CONTRIBUTING.md to improve clarity and guidance for new contributors

iambel requested review from karasowles, AndreaGriffiths11, LadyKerr and cassidoo as code owners May 6, 2025 17:56

karasowles suggested changes May 6, 2025

View reviewed changes

docs:improve CONTRIBUTING.md

1678b0d

correcting some details based on feedback received

adiati98 reviewed May 7, 2025

View reviewed changes

docs: CONTRIBUTING.md update

099a61e

adiati98 reviewed May 19, 2025

View reviewed changes


		The Maintainer Month website is maintained by the Open Source team at GitHub. You can reach out at <maintainermonth @ github .com>
		The Maintainer Month website is maintained by the Open Source team at GitHub. You can reach out at <maintainermonth@github.com> 💚


		> Important: Do not modify variable names in frontmatter sections (between `---`). These are required for the website to function properly.
		> 📌 Important: Do not modify variable names in frontmatter sections (between `---`). These are required for the website to function properly.

	> 📌 Important: Do not modify variable names in frontmatter sections (between `---`). These are required for the website to function properly.
	> [!IMPORTANT]
	> Do not modify variable names in frontmatter sections (between `---`). These are required for the website to function properly.

	git clone https://github.com/iambel/maintainermonth.git
	git clone https://github.com/YOUR-USERNAME/maintainermonth.git

	- [Adding a New Resource
	](#adding-a-new-resource)
	- [Adding a New Resource](#adding-a-new-resource)

	- [Making Code Changes
	](#making-code-changes)
	- [Making Code Changes](#making-code-changes)

		- [Setting Up Your Environment
		](#setting-up-your-enviroment)

	- [Setting Up Your Environment
	](#setting-up-your-enviroment)
	- [Setting Up Your Environment](#setting-up-your-enviroment)

docs: improve CONTRIBUTING.md #327

Are you sure you want to change the base?

docs: improve CONTRIBUTING.md #327

Uh oh!

Conversation

iambel commented May 6, 2025

Uh oh!

karasowles left a comment

Choose a reason for hiding this comment

Uh oh!

iambel commented May 6, 2025

Uh oh!

adiati98 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adiati98 May 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adiati98 May 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iambel commented May 12, 2025

Uh oh!

iambel commented May 19, 2025

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adiati98 left a comment •

edited

Loading

adiati98 May 7, 2025 •

edited

Loading

adiati98 May 7, 2025 •

edited

Loading