diff --git a/rules/use-readme-templates/bad-readme.png b/rules/use-readme-templates/bad-readme.png new file mode 100644 index 0000000000..13bd296617 Binary files /dev/null and b/rules/use-readme-templates/bad-readme.png differ diff --git a/rules/use-readme-templates/bronze-standard-readme.png b/rules/use-readme-templates/bronze-standard-readme.png new file mode 100644 index 0000000000..634c18228f Binary files /dev/null and b/rules/use-readme-templates/bronze-standard-readme.png differ diff --git a/rules/use-readme-templates/gold-standard-readme.png b/rules/use-readme-templates/gold-standard-readme.png new file mode 100644 index 0000000000..0662c66acc Binary files /dev/null and b/rules/use-readme-templates/gold-standard-readme.png differ diff --git a/rules/use-readme-templates/good-readme.png b/rules/use-readme-templates/good-readme.png new file mode 100644 index 0000000000..9170eff80f Binary files /dev/null and b/rules/use-readme-templates/good-readme.png differ diff --git a/rules/use-readme-templates/rule.md b/rules/use-readme-templates/rule.md new file mode 100644 index 0000000000..0d2ca4cb9e --- /dev/null +++ b/rules/use-readme-templates/rule.md @@ -0,0 +1,64 @@ +--- +type: rule +tips: "" +title: Do you use README templates? +seoDescription: Learn how to boost your GitHub Project's audience reach and + impact with README Templates +uri: use-readme-templates +authors: + - title: Caleb Williams + url: https://www.ssw.com.au/people/caleb-williams/ +created: 2025-01-10T18:23:00.000Z +guid: 0c108f17-9d2c-4253-a976-5d13b0e5ac3a + +--- + +A README can often be a potential contributor's first impression of your project. It communicates the project's vision, how to contribute to the project and places where people can donate and installation instructions. + + + +Having a README template ensures that you’re checking all of the boxes for ensuring that contributors have an easy time getting your project up and running and beneficiaries know how to use your code. + +README templates can be beneficial for ensuring your personal projects have the features necessary for gaining momentum and ensuring that projects done at an organizational level are up to a high standard. + +::: bad +![Figure: Bad example - README created without a template](bad-readme.png) +::: + +This README is very basic, the setup instructions are limited and there is room for improvement: + +* Bullet points could help better communicate selling points +* Diagrams +* Photos and marketing material +* Multiple level headings +* Known Issues + +::: good +![Figure: Good example - The ReadMe above clearly outlines the goals of the project and provides new developers with enough context to get started](good-readme.png) +::: + +It's important to keep your README templates in a convenient place to ensure that you can quickly bootstrap a project when you get started. + +## What does an awesome README template look like? + +The templates should vary depending on the overall goal of the project. As you go further down the tier list from gold standard to bronze standard README you’ll notice that the emphasis shifts away from growing the project’s social media presence and notoriety and instead focuses on the bare bones instructions required to run the project and contribute. + +### Gold standard READMEs + +Gold standard READMEs are primarily for public facing projects. They should primarily focus on getting the audience invested and excited to see the project succeed. This fosters a healthy community that will band together to see the project succeed + +Social media links, exciting graphics and entertaining explanation videos are of paramount importance so that the community remains invested and has a sense of ownership for the project. + +![Figure: A Gold standard README template](gold-standard-readme.png) + +### Silver standard READMEs + +The silver README standard prioritizes a smooth developer experience as well as making the project handover easier. Note how the social media links have been removed and instructions for setting up the project have been brought to the forefront at the top of the README. The instructions for contributing are also much more detailed. + +![Figure: A Silver standard README](silver-standard-readme.png) + +### Bronze READMEs + +The bronze README standard is designed for projects where scalability is a low priority, and the scope of the project is limited. The README template should only be used to expedite making the repository public, or accessible to any contributing team members. In this case approaches to make the project more marketable take a back seat in favor of making the README quick and easy to digest. + +![Figure: A Bronze standard README](bronze-standard-readme.png) diff --git a/rules/use-readme-templates/silver-standard-readme.png b/rules/use-readme-templates/silver-standard-readme.png new file mode 100644 index 0000000000..8710c2fa36 Binary files /dev/null and b/rules/use-readme-templates/silver-standard-readme.png differ