Improve the list guidelines and pull request guidelines (pull request template)

[yishangupenn]

Copied from upstream: sindresorhus/awesome#2984
Original author: @wongyah
Originally opened: 2024-02-27

---

Why I open the pull request

I read through the pull request template and other files before I started to create my list Awesome Technical Writing Learning. I stayed confused during my reading:

• Why should I know how to write a pull request when I don't even have an awesome list? ("Requirements for your pull request" is the first section.)
• Why I just know how to create the awesome list when I am ready to submit the pull request? ("Requirements for your Awesome list is the second section.)
• Why I just know there are requirements for repository settings so late? (repository name, default branch name, and topics setting are not at the beginning of the file. So do requirements on other parts of the list.)

What I did

• Separate the requirements for the awesome list from those for the pull request, resulting in two files named "awesome-list-guidelines.md" and "pull-request-guidelines.md".
• Classify the requirements in different categories, such as repository settings, list profile, table of contents, list body, ect.
• Create a section for each category.
• Arrange the sections based on the journey of list creation and submission, so that the list owners can follow the guidelines to create their list.
• Add a table of contents for each guidelines file, so that the list owners can place the relevant requirements immediately.

What is in question

There are several sentences in the pull request template I maybe didn't understand correctly. I added a comment for each of them, like this:

<!--! What do you mean by "Non-generated Markdown file in a GitHub repo."? Maybe I didn't get your point here. -->
> [!NOTE]
> Do not use generated Markdown files in the list repository.

<!--! Is it the function of Yeoman generator? I didn't understand the readme of Yeoman generator. -->
> [!TIP]
> You can use [Yeoman generator](https://github.com/dar5hak/generator-awesome-list) to create a new awesome list automatically.

If you like the style of the improved guidelines, please feel free to review and comment on how to make it better. Thanks!