search

json-schema-org / website

JSON Schema website
https://json-schema.org
Other
67 stars 174 forks source link

[📝 Docs]: Enhance the Contribution Docs Guide for Better Readability and Structure #1124

Open fee-sah-yor opened 1 day ago

fee-sah-yor commented 1 day ago

What Docs changes are you proposing?

Description:

Hi, I read through the contribution guide and noticed that some parts of the introduction can be a bit confusing, especially for beginners. I found myself rereading certain sections multiple times to fully understand the process. Here are a few suggestions to improve the guide’s clarity:

  1. Reorder Items in "Before You Start":

    • I suggest moving "Read the style guide" to the third item in the "Before You Start" list. This way, beginners can go through the style guide first, and then proceed to fork the JSON schema repo. This feels more intuitive. Reword Installation Instructions:

  2. Reword Installation Instructions:

    • The line "Install the JSON schema website on your computer" could be rephrased to: "Fork the repo and follow these steps to install the JSON schema website on your computer." This change better reflects the steps outlined later in the guide, particularly in the "Work on an Existing Issue" section.

  3. Format the "Work on an Existing Issue" Section:

    • The instructions in this section could be formatted as a bulleted list with indented steps for better readability. It’s currently harder to follow as a block of text.

i believe these changes as well as others will help beginner contributors interacting with the guide for the first time understand it better.

Code of Conduct

github-actions[bot] commented 1 day ago

Welcome to the JSON Schema Community. We are so excited you are here! Thanks a lot for reporting your first issue!! 🎉🎉 Please make sure to take a look at our contributors guide if you plan on opening a pull request. For more details, check out the README.md file.