Skip to content

Instantly share code, notes, and snippets.

@theecrit

theecrit/readme.md

Last active January 21, 2024 16:59
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save theecrit/d69671774c7881505e0ffa9643358eb7 to your computer and use it in GitHub Desktop.
Save theecrit/d69671774c7881505e0ffa9643358eb7 to your computer and use it in GitHub Desktop.
Download ZIP
Docs For Alignment: ReadMe Template
Raw
readme.md

Project title and description

Include a project description that explains what your project is and why it exists. Aim for no more than 3-5 concise sentences. For example, you might say:

{Project Name} is a project of {Your Brigade}. {Your Brigade} is a brigade of a Code for America that exists to {your mission}. {Project Name} helps {target users} accomplish {goal of project}. The {app/site/thing you're building}'s main features include {very brief feature descriptions}.

Project context

Civic projects often exist within a larger context that may include multiple stakeholders, historic relationships, associated research, or other details that are relevant but not required for direct contributions. Gathering these details in one place is useful, but the ReadMe isn't that place. Use this section to link to a Google Doc or other documentation repository where contributors can dig in if they so choose. This is also a good place to link to your Code of Conduct.

Technology used

  • Each platform or framework should get its own bullet.
  • Each platform should include an active link to the official documentation.

How to contribute

Explain the different ways people can contribute. For example:

  • Join the team {on Slack/at our weekly hack night/etc}.
  • To help with user research, {do ABC}.
  • To provide design support, {do XYZ}.
  • To contribute to the code, follow the instructions below.

Remember to provide direct links to each channel.

Installation instructions

  1. Step-by-step instructions help new contributors get a development environment up and running quickly.
  2. You'll want to find the balance between being specific enough for novices to follow, without being so specific that you reinvent the wheel by providing overly-basic instructions that can be found elsewhere.
  3. Feel free to adapt this section and its sub-sections to your own processes.
  4. Alternatively, you can move everything from Installation instructions through Testing to a separate Contributing.md file to keep your ReadMe.md more succinct.

Working with issues

  • Explain how to submit a bug.
  • Explain how to submit a feature request.
  • Explain how to contribute to an existing issue.

If you want your issues submitted in a particular format, explain how (or create issue templates).

Working with forks and branches

  • Explain your guidelines here.

Working with pull requests and reviews

  • Explain your process.

Testing

  • Provide instructions.

Contact info

Include at least one way (or more, if possible) to reach your team with questions or comments.

Licensing

Include details about the project's open source status.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment