Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📝 New rule - Do you use README templates? #9765

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added rules/use-readme-templates/bad-readme.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added rules/use-readme-templates/good-readme.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
64 changes: 64 additions & 0 deletions rules/use-readme-templates/rule.md
Original file line number Diff line number Diff line change
@@ -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.

<!--endintro-->

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)
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading