From 8e3fa802e37a498c957ad4191047a49f4a4ce569 Mon Sep 17 00:00:00 2001 From: Joanne Fung Date: Thu, 26 May 2022 16:49:49 -0600 Subject: [PATCH] Added README template and template guide for review --- readme/template-guide-readme.md | 101 ++++++++++++++++++++++++++++++++ readme/template-readme.md | 101 ++++++++++++++++++++++++++++++++ 2 files changed, 202 insertions(+) create mode 100644 readme/template-guide-readme.md create mode 100644 readme/template-readme.md diff --git a/readme/template-guide-readme.md b/readme/template-guide-readme.md new file mode 100644 index 00000000..a2977642 --- /dev/null +++ b/readme/template-guide-readme.md @@ -0,0 +1,101 @@ +# README Template Guide + +Read this document before you start working on the README template. + + +*Note: As your project evolves and grows, so should your README file. READMEs should be revisited regularly to ensure relevant information is captured for new users.* + +## Why do I need a README? +READMes are the first document users find and read. All projects include a README, and users will expect to find one in your project's root folder. A README tells users what they need to know about your project, if the project is relevant to the user, and how users can engage with the project. Your README is your project's first impression. + +In some cases, larger projects may include sub-READMEs, or separate, smaller READMEs that support subfolders in the project. + +## Content of the README template guide +The following sections provide guidance and context on how to fill out the README template. + +### About the "Project logo and badge" section +This section is optional. + +A project logo can be helpful for users to visually identify your project. + +Embed relevant badges to your README to add credibility to your project. Badges highlight important information and can help users determine project fit quickly. [Learn more about badges.](https://github.com/badges/shields) + +### About the "Project name" section +The project name should be prominent in the README and easy for users to identify. You may want to consider adding the following to help identify the project: +- Project URL +- Name(s) of project owner(s) + +*Note: Consider the stage your project is at and how much information is required in your README. Names associated with the project may be better located in a separate contact document.* + + +### About the "Table of contents" section +This section is optional. + +A table of contents can be useful in the case of lengthy READMEs. As the project evolves, the README may require a table of contents for information organization. + +*Note: For Markdown files, GitHub now automatically generates a table of contents in the file Header. [Learn more about the GitHub TOC here.](https://github.blog/changelog/2021-04-13-table-of-contents-support-in-markdown-files/)* + +### About the "Project description" section +The project description is the most critical part of your README. Describe what the project does, why the reader should care about your project, and how it can help the reader. This section should be succinct, use strong verbs, and help the reader determine whether the project is of use to them. + +Screenshots or videos may also be included in this section to help readers understand your project. Any assets you direct users to should exist in the repo. + +You can use the below project description format to start filling in your section. An example is provided. + + +With *(this project)* you can *(verb)* *(noun)*... + +*(This project)* helps you *(verb)* *(noun)*.... + +Unlike *(alternative)*, *)this project)* *(verb)* *(noun)*... + + +--- + +Example: With the Chronologue project, you can discover astronomical events throughout documented history. This project helps you understand the evolution of space in a streamlined format. Unlike googling and searching for important astronomical events, the Chronologue project outlines historical events with an easy to use and simple interface. + +--- + +### About the "Who is the project for" section +Identify your project audience and state who can use the project and under what terms. + +### About the "Project dependencies" section +List any pre-requisites a user needs to interact with your project. Include relevant links to installation instructions or resources. + +### About the "Instructions for using project" section +Describe in clear steps how to get, install, configure, run, and troubleshoot the project. Use a table for troubleshooting common issues to clearly identify issues and solutions. + +### About the "Additional documentation" section +Provide additional documentation for users by including links and brief descriptions. Examples of additional documentation include: +- Project website +- Twitter handle(s) of project/project owner(s) +- Relevant examples +- Next steps +- Features planned +- Known bugs +- Documentation files +- Help command(s) + + +### About the "How to get help" section +Provide guidance for users seeking assistance by including links and brief descriptions. Examples of help resources include: +- Google group/mailing list +- Email address(es) +- IRC, Slack, or Discord channels +- Bug trackers +- Stack overflow + +### About the "Contributing guidelines" section +Provide clear instructions on how users can contribute to the project by linking to your contributing guidelines document or by embedding the guidelines in your README. + +*Note: Consider the stage your project is at. While most contributing guidelines are provided in a separate document, a smaller project may include guidelines in the README. A Good Docs contributing guidelines template is available. [LINK TO KAYLA'S TEMPLATE].* + + +### About the "Terms of use" section +The Terms of use section should include your project license and other relevant licensing information. + +## Additional README resources +- [Daniel Beck's README checklist](https://github.com/ddbeck/readme-checklist/blob/main/checklist.md) +- [Daniel Beck's Write the Docs "Write the Readable README" presentation](https://www.writethedocs.org/videos/na/2016/write-the-readable-readme-daniel-beck/) + +If there are other README resources you think can be linked in this guide, please [open an issue](https://github.com/thegooddocsproject/templates/issues) to let us know! \ No newline at end of file diff --git a/readme/template-readme.md b/readme/template-readme.md new file mode 100644 index 00000000..f1c91ed7 --- /dev/null +++ b/readme/template-readme.md @@ -0,0 +1,101 @@ +# README Template + +*{Before using this template, read the accompanying README template guide}.* + +## {Project} logo and badges +{This section is optional. Share your logo and add relevant badges to your README.} + +## {Project Name} +{Optional: Include the project URL and the project owner name} + +## Table of contents +{This section is optional.} +1. Heading 1 +2. Heading 2 +3. Heading 3... + +## Project description +{Project description example available in README template guide} + +With *{Project Name}* you can *(verb)* *(noun)*... + +*{Project Name}* helps you *(verb)* *(noun)*.... + +Unlike *(alternative)*, *{Project Name}* *(verb)* *(noun)*... + +{Optional: Include screenshots and/or demo videos} + +## Who this project is for +This project is intended for {target audience} who want to {audience objective}. + +## Project dependencies +To use {Project Name}, you will need: +- Prerequisite 1 +- Prerequisite 2 +- Prerequisite 3... + +## Instructions for using {Project Name} +Get started with {Project Name} by {first step here} + +### How to get {Project Name} +1. {Write the step here. Use a verb to start.} + + {Explanatory text here} + + {Optional: Code sample or screenshot that helps your users complete this step} + +2. {Write the step here. Use a verb to start.} + + a. {Substep 1} + + b. {Substep 2} + +### How to install {Project Name} +1. {Write the step here. Use a verb to start.} + +2. {Write the step here. Use a verb to start.} +### How to configure {Project Name} +1. {Write the step here. Use a verb to start.} + +2. {Write the step here. Use a verb to start.} +### How to run {Project Name} +1. {Write the step here. Use a verb to start.} + +2. {Write the step here. Use a verb to start.} +### How to troubleshoot {Project Name} +| Issue | Solution | +| ----------- | ----------- | +| {Describe the issue here} | {Write solution here} | +| {Describe the issue here} | {Write solution here} | +| {Describe the issue here} | {Write solution here} | + +Other troubleshooting supports: +- {Link to FAQs} +- {Link to runbooks} +- {Link to other relevant support information} + + +## Additional documentation +{Include links and brief descriptions to additional documentation. Examples provided in README template guide.} + +More information can be found: +- Reference link 1 +- Reference link 2 +- Reference link 3... + + +## How to get help +{Include links and brief descriptions for support resources. Examples provided in README template guide.} + + +- Reference link 1 +- Reference link 2 +- Reference link 3... + +## Contributing guidelines +{Include a link to your contributing guide here. If you do not have a contributing guide, incorporate the information in the README}. + + + +## Terms of use +{Project Name} is licensed under {license}. \ No newline at end of file