Skip to content

Latest commit

 

History

History
487 lines (363 loc) · 24.9 KB

readme_guidelines.md

File metadata and controls

487 lines (363 loc) · 24.9 KB
Raw

README Guidelines

General instructions for crafting a README file are provided here, tailored for PRG projects but applicable to any type of project.

Table of Contents

README File

Warning

A README file is REQUIRED for ALL tiers.

  • Use the templates in the next section as a starting point for your profile README (especially if you're using PRG).

Templates

For templates and examples of READMEs, see the templates directory. Templates are broken down by the four categorized tiers of projects: Platinum, Gold, Silver, and Bronze.

Markdown

GitHub Markdown Alerts

GitHub has a special syntax for alerts in Markdown files:

Note

Highlights information that users should take into account, even when skimming.

Tip

Optional information to help a user be more successful.

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Caution

Negative potential consequences of an action.

Read more about GitHub Markdown Alerts.

Disclaimer

Important

I only mentioned the important parts of a README file, there are many other things you can add to your README file that I didn't mention here. Feel free to add whatever you want to your README file including new sections, images, GIFs, etc. Below is a description of each section of a PRG README and what it should contain. Depending on the tier of your project, some sections are REQUIRED while others are OPTIONAL.

Note

Your Profile README does not need to adhere to the PRG guidelines defined in this document, but it is encouraged to include the PRG Profile Badge to link to your PRG Collection.

Below is a description of each section of a PRG README and what it should contain:

Header

Warning

REQUIRED section for ALL tiers.

  • The header consists of two parts: the Header Icon and the Badges.
  • This should be the first section of your README.

Header Icon

  • The header icon is a either a logo/icon or a custom banner.

  • A banner should always be used for Platinum/Gold projects, while a logo/icon should be used for Silver/Bronze projects.

  • A banner is a custom design created to represent your project.

    • I use Sketch to create my banners and designs, but you can use any design software you want.
    • See Brand Guidelines for more information on creating banners and other graphics for your project.

  • For Silver/Bronze projects, you can use a custom icon or a logo of the technology you used to develop your project instead of a banner.

    [!TIP]
    There are plenty of free logos out there for most technologies, just make sure you give credit to the creator of the logo if it's required (follow the license for the image).

  • e.g. My logo for my Silver Project, UWP Audio Recorder:

Tip

Append #gh-dark-mode-only or #gh-light-mode-only to the end of the image URL to only show the image in dark or light mode respectively. Be sure to have both a dark and light version of the image when necessary. More on this (shameless plug) here.

  • e.g. A logo for a Bronze project that showcases JavaScript code:
JavaScript

  • The header icon or banner should always be clickable and take you to your project's website/product/demo.
    • If you do not have a website/product/demo, you should link it to your projects repository main branch.

Badges

  • Badges are a great way to showcase the technologies, frameworks, and languages used in your project.
  • Badges are generated using Shields.io.
  • You should include all major technologies, frameworks, and languages used in your project (one badge per technology). This badge should contain the technology name and version you used to develop your project.
    • e.g. Python Badge
    • e.g. Node.js Badge
  • The badge color should match the color of the technology's logo. Use a browser extension like ColorZilla to get the exact color code of a logo from a website.
  • The badge should hyperlink to the technology's website or version release page (whatever you think is more appropriate).
  • Optionally you can add badges for your email, website, and GitHub profile so people can contact you or follow you. You can also add a link to your BuyMeACoffee page if you have one to support your work.
    • e.g. Email Badge
    • e.g. GitHub Badge
    • e.g. BuyMeACoffee Badge

Note

To demonstrate your project adheres to PRG, please include the appropriate badge at the top of your repository README. See the top of this README for an example.

Resources:

Shields.io - A website for generating badges.
GitHub Workflow Status Badge

Divider

A horizontal divider is a great way to separate the top of your README from the rest of the content. Use a divider to separate your README into two sections: the header (after the badges and another before the table of contents) and the footer section (after the credits but before the footer image).

  • e.g. ---------------

Title

Warning

REQUIRED section for ALL tiers. The header of "Title" should not be included in your README, just the title of your actual project.

  • The title should be the name of your project (without underscores or dashes).

Description

Warning

REQUIRED section for ALL tiers. You do not need to include a header called "Description" for this section, just the description under the title.

  • The description should be a short paragraph describing what your project is and what it does after the title.
  • This should be the first section after the badges.
    • e.g. "A Python, Django, Plotly, and Pandas web application that visualizes river data pulled using an API from the United States Geological Survey (USGS)."
  • Add screenshots of your project below the description and throughout the rest of the README as needed.
    • This is optional, but highly recommended especially for Platinum and Gold projects.
    • Animations in the form of GIFs are also a great way to showcase your project.
      • I use GiFox to create GIFs of my projects, but you can use any GIF creation software you want.
      • Snagit is another great tool for creating GIFs and screenshots.
      • Both of these tools are paid, but there are plenty of free alternatives out there as well.

Table of Contents

Warning

REQUIRED section for Platinum, Gold, and Silver tiers. Bronze tier projects do not require this section, but feel free to add it if you want.

  • The table of contents should be a list of links to each section of your README.
  • This should be the second section after the description.

Features

Warning

REQUIRED section for Platinum and Gold tiers only. Silver and Bronze tier projects do not require this section, but feel free to add it if you want.

  • This section should contain a list of features for your project.
  • Explain what each feature does and how it works.
  • You can also add screenshots of each feature if you want.

Background Story

Warning

REQUIRED section for Platinum and Gold tiers only. Silver and Bronze tier projects do not require this section, but feel free to add it if you want.

  • The background story should be a short paragraph describing why you created the project and what inspired you to create it.

Definitions

Warning

OPTIONAL section for ALL tiers.

  • This section should contain a list of definitions for any terms or acronyms used in your project.

Getting Started

Warning

REQUIRED section for ALL tiers.

  • You can break this section down into further subsections if you want (such as below: Dependencies, Configuration, Running Locally, Deployment, etc.).
  • Otherwise, you can just include a list of steps to get your project up and running under Getting Started.

Dependencies

Warning

OPTIONAL section for ALL tiers.

  • This section should contain a list of dependencies for your project.
  • There is no need to list every single dependency, just the major ones.
  • There's also no need to list the version or website for each dependency (this will be done in the Resouces area, more on that soon), just the name is fine.
    • e.g. This project makes use of several libraries and frameworks:
      - Python: For the application logic.
      - Django: For web application functionality.
      - Plotly: For creating interactive visualizations.
      - Pandas: For data manipulation and analysis.
      - Requests: For making API calls.
      - Python-Decouple: For storing sensitive information in a .env file.
  • You can use a tool like Dependabot to automatically generate a list of dependencies for your project.

Resources:

Dependabot

Configuration

Warning

OPTIONAL section for ALL tiers.

  • Include any configuration information for your project here.

Installation

Warning

OPTIONAL section for ALL tiers.

  • This section should contain a list of steps to get your project up and running.
  • Utilize code blocks to show the commands needed to run your project.
  • e.g.
    1. Clone this repository.
    2. Create a virtual environment: python -m venv venv.
    3. Install the dependencies.
    4. Run the application: 
      python manage.py runserver

Deployment

Warning

OPTIONAL section for ALL tiers.

  • Include any deployment information for your project here.

What's Inside?

Warning

REQUIRED section for Platinum and Gold tiers only. Silver and Bronze tier projects do not require this section, but feel free to add it if you want.

  • This section should contain a list of files and folders in your project and what each one does.

  • Generally, you should only list the main files and folders in your project, not every single file.

  • Use a tree diagram to show the relationship between files and folders:

    • e.g.
    ├── README.md # This file.
├── config.py # A file that contains sensitive information (excluded from this repository).
├── manage.py # A command-line utility that lets you interact with this Django project in various ways.
├── requirements.txt # A list of Python packages required to run this project.
├── static # A directory for static files that are used in this Django project.
│   ├── css # A directory for CSS files.
│   │   └── styles.css # A CSS file that contains the styles for the application.
│   ├── data # A directory for data files.
│   │   └── river_charts.csv # A CSV file that contains the float dates for the application.
│   └── images # A directory for image files.
├── templates # A directory for HTML templates.
│   └── river_charts # A directory for HTML templates specific to the river_charts app.
│       ├── error.html # An HTML template that displays an error message.
│       └── index.html # An HTML template that displays the application.
├── views.py # A file that contains the application logic.
├── VERSION # A file that contains the current version of the application.
├── LICENSE # A file that contains the license for this project.
└── CREDITS # A file that contains the credits for this project.

  • You can use a the following resources below to generate a tree diagram for your project.

Resources:

An online tree-like utility for generating ASCII folder structure diagrams Project Tree Generator ASCII Tree Generator VSCode Extension

Closing

Warning

REQUIRED section for Platinum and Gold tiers only. Silver and Bronze tier projects do not require this section, but feel free to add it if you want.

  • Add any closing notes or remarks here.

Limitations

Warning

OPTIONAL section for ALL tiers.

  • This section should contain a list of limitations for your project.

Disclaimer

Warning

OPTIONAL section for ALL tiers.

  • Include any disclaimers for your project here.
  • e.g. "This project is not affiliated with the United States Geological Survey (USGS)."

What's Next?

Warning

REQUIRED section for Platinum and Gold tiers only.

  • Include any future plans for your project here.

Project

Warning

REQUIRED section for Platinum and Gold tiers only.

  • Include a link to your project plan here on GitHub if you do create one.

Contributing

Warning

REQUIRED section for Platinum and Gold tiers only.

  • GitHub is about collaboration and contribution, so this is why its essential to include a section on how to contribute to your best projects.
  • Include any information on how to contribute to your project here.
  • Include a CONTRIBUTING file in your repository for more detailed information on how to contribute to your project.

Resources

Warning

REQUIRED section for Platinum, Gold, and Silver tiers. Bronze tier projects do not require this section, but feel free to add it if you want.

  • This section should contain a list of resources used to create your project.
  • Include the name of the resource, a link to the resource, and a short description of what the resource is.
    • e.g. Plotly - A Python graphing library that makes interactive, publication-quality graphs online.
    • e.g. Django - A high-level Python Web framework that encourages rapid development and clean, pragmatic design.
    • e.g. Pandas - A fast, powerful, flexible and easy to use open source data analysis and manipulation tool, built on top of the Python programming language.

License

Warning

REQUIRED section for ALL tiers.

  • Describe the license for your project here.
  • I found it helpful to break down what license I choose based on the PRG tier of the project:
    • Platinum - GNU GPLv3 or No License (if you want to keep your code private)
    • Gold - GNU GPLv3
    • Silver - MIT
    • Bronze - The Unlicense
  • I chose GNU GPLv3 for my Platinum and Gold projects.
    • Why? I spent a lot of time on my Platinum and Gold projects and I want to protect my work as much as possible.
    • I do not want people to use my code to profit off of it without my permission which is why I chose this more restrictive license.
  • I chose MIT for my Silver projects.
    • Why? I put more work into my Silver projects than my Bronze projects, so I want to protect my work a little more but still allow people to use my code in their own projects by giving me credit for it.
  • I chose The Unlicense for my Bronze projects.
    • Why? Because I want to encourage people to use my code in their own projects, even if they don't give me credit for it.
  • Include a LICENSE file in your repository for more detailed information on the license for your project.
  • The above licenses are the licenses I chose for my projects, but you can choose whatever license you want for your projects.
  • A list of licenses can be found here.

Footer

Warning

REQUIRED section for ALL tiers.

  • The footer consists of two parts: the Credits and the Footer Icon.
  • This should be the last section of your README.

Credits

  • Include a credit block for each person who contributed to your project.
  • If you worked on the project by yourself, you can just include your name and other details such as:
    • Author: - Your name + a link to your GitHub profile.
    • Email: - Your email + a link to your email.
    • Website: - Your website + a link to your website.
    • Reference: - Main Branch + a link to the main branch of your repository.
  • Include a CREDITS file in your repository for more detailed information on the credits for your project.

Footer Icon

  • The footer icon should contain a image of your application's icon (never a banner) for all tier projects.
  • The footer icon should also be a centered clickable image link to your personal website, GitHub profile, or main repo branch for said project.
  • Above the footer icon, you should include a divider to separate the footer icon from the rest of the README.
    • e.g. ---------------
  • See the bottom of this project README for an example.

Resources

General Resources:

General README Information:

README Generators:

Open Source README Templates:

Markdown: