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

* Create Rule “use-readme-templates/rule” * replaced images with higher quality versions * added missing image * added my people profile link * Update rule.md Hey @Calinator444 O fixed the Markdown for bad and good examples * added rule to architecture and code review category * Added related rules back and forth between readme templates and awesome readmes rule * small improvements * conolidated info for readme into a single paragraph * cleaned up unused readme tempates and added a link to the awesome template * Update rule.md * Update rule.md * Update rules/use-readme-templates/rule.md Co-authored-by: Matt Wicks [SSW] <wicksipedia@users.noreply.github.com> * Update rules/use-readme-templates/rule.md Co-authored-by: Matt Wicks [SSW] <wicksipedia@users.noreply.github.com> * Update rules/use-readme-templates/rule.md Co-authored-by: Matt Wicks [SSW] <wicksipedia@users.noreply.github.com> * Update rules/use-readme-templates/rule.md Co-authored-by: Matt Wicks [SSW] <wicksipedia@users.noreply.github.com> --------- Co-authored-by: Tiago Araújo [SSW] <tiagov8@gmail.com> Co-authored-by: Matt Wicks [SSW] <wicksipedia@users.noreply.github.com>
SSWConsulting · Feb 7, 2025 · c71fdf8 · c71fdf8
1 parent 8061780
commit c71fdf8
Show file tree

Hide file tree

Showing 6 changed files with 54 additions and 0 deletions.
diff --git a/categories/software-engineering/rules-to-better-architecture-and-code-review.md b/categories/software-engineering/rules-to-better-architecture-and-code-review.md
@@ -10,6 +10,7 @@ index:
   - do-you-conduct-an-architecture-review-after-every-sprint
   - awesome-documentation
   - awesome-readme
+  - use-readme-templates
   - architecture-diagram
   - do-you-document-the-technologies-design-patterns-and-alm-processes
   - spike-vs-poc

diff --git a/rules/awesome-readme/rule.md b/rules/awesome-readme/rule.md
@@ -14,6 +14,7 @@ authors:
     url: https://www.ssw.com.au/people/william-liebenberg
 related:
   - awesome-documentation
+  - use-readme-templates
 created: 2024-07-18T13:42:55.753Z
 guid: d84cad17-a3d0-4e1f-aaba-f2cd7c950d86
 ---

diff --git a/rules/use-readme-templates/bad-readme.png b/rules/use-readme-templates/bad-readme.png
diff --git a/rules/use-readme-templates/good-readme.png b/rules/use-readme-templates/good-readme.png
diff --git a/rules/use-readme-templates/readme-template.png b/rules/use-readme-templates/readme-template.png
diff --git a/rules/use-readme-templates/rule.md b/rules/use-readme-templates/rule.md
@@ -0,0 +1,52 @@
+---
+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/
+related:
+  - awesome-readme
+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 ideal README should foster contributions for a project organically. It should provide all the relevant information a contributor user would need to get the project up and running, make code changes, and deploy to production if necessary. It should also contain a number of clearly located social media links so followers of the project users can keep an ear to the ground for updates. Followers who see regular updates via social media are more likely to feel actively involved and will commit to the project's success.
+
+We've created a README template with placeholders where you can add all of the relevant information for your project to ensure that it's a success. Bear in mind that not all of the information listed will be relevant to your particular project. For instance, closed-source projects more than likely won't contain social media or sponsorship links. Feel free to remove any placeholders that aren't relevant to your project. 
+
+You can find the template here on GitHub [SSWConsulting/SSW.AwesomeReadme.Template/readme-template.md](https://github.com/SSWConsulting/SSW.AwesomeReadme.Template/blob/main/readme-template.md)
+
+::: good
+![Figure: Good example - A standard README template on GitHub](readme-template.png)
+:::