Skip to content

Instantly share code, notes, and snippets.

@cobalt88

cobalt88/README-Template.md

Last active January 5, 2024 03:33
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save cobalt88/f166de73f39e9a244d04570799780733 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save cobalt88/f166de73f39e9a244d04570799780733 to your computer and use it in GitHub Desktop.
Download ZIP
Commented Templates
Raw
README-Template.md

Readme Template

License: MIT

Table of Contents

Description

Overall description of the project, what does it do, why does it do it, is it done or in development, ect

![Alt text]('link thingy')

Installation Instructions

Example: - Begin by forking the repository or creating a standalone instance with git clone. - Once your local repository is set up, open your terminal, cd into the projects rood directory cd c:/new-repo and run the following command for initial set up: npm i.

or any other instructions someone might need to either install your application. If there are separate instructions for Development thn for normal use specify what to do for each scenario.
For example, are these instructions intended for someone who needs to set up a local instance of the repository for a personal project or to be able to contribute to your project?
Or is there an installation process for your application that is required to make it run locally? If your project is something like a deployed website or an API thats able to be interacted with remotely its almost always going to be the first option.

How To Use

What will users need to know about your app, this is a good spot for basic documentation or links to your documentation if theres a lot of it. If you have a ton of documentation like route maps, model trees, setup files for Postman or Insomnia, overall architecture notes, and so on, I would recommend adding them to a docs folder in your root directory and referencing them here.

Contribution Guidelines

What are the guideline for prospective contributors? Things to keep in mind and ask yourself:

  • Do you have a particular naming scheme or versioning system?
  • Are there any protected branches?
  • Is peer review set up?
  • Do you have any Lint requirements?
  • would you prefer contributors to work in a separate branch or a fork?
  • And so on, try to avoid having so many guidelines it looks like the fine print section of a loan agreement. 5-10 guidelines is a good number to hover around for most projects, large or small. If your guidelines are more complicated than that make them a separate document and highlight the core principles here.

Application Tests

If your application has any tests or validation routines this is where you should inform people about them. Again, if you have a ton of test conditions, like one for every API route, and one for every model, and one for every major function, and so on, just highlight the really important stuff here and write out a fully detailed test condition document to add to your docs folder.

license

Example: This project is licensed under the MIT license.
For more information about this license and what it entails visit: https://opensource.org/licenses/MIT
Note: Do be aware there is a license tag at the top of this document, if you change the license to be something other than MIT don't forget to change or remove the MIT License badge at the top.

About The Author

How can people get in touch, view your other work, support your projects, and so on.

Example: I hope you enjoy the application, if you have any questions, comments, concerns, feedback, ect, please feel free to open a new issue or reach out directly. Don't forget to check out some of my other projects on github while your here!

Raw
asyncCrudRoute.js
router.get("/", async (req, res) => {
try {
//server logic/database queries go here
const response = await Model.find(); // example query;
//return whatever data you retrieved from the database to the client/frontend.
res.status(200).json(response);
} catch (err) {
//this type of error handling is great for development environments but can break things in production environments, so use with caution.
res.status(500).json({ message: `Unexpected error encountered in (route name here): ${err.message}` });
//once in a deployed production environment switch to using this so your page doesn't break and display a weird error message when the client side receives an unexpected json object.
console.log(`Unexpected error encountered in (route name here): ${err.message}`);
}
});
//see async API Route Template.js for a non commented version of this template.
router.get("/", async (req, res) => {
try {
//server logic/database queries go here
//return whatever data you retrieved from the database to the client/frontend.
res.status(200).json(response);
} catch (err) {
//this type of error handling is great for development environments but can break things in production environments, so use with caution.
res.status(500).json({ message: `Unexpected error encountered in (route name here): ${err.message}` });
//once in a deployed production environment switch to using this so your page doesn't break and display a weird error message when the client side receives an unexpected json object.
console.log(`Unexpected error encountered in (route name here): ${err.message}`);
}
});
Raw
Route-Map-Template.md

API Route Map

This document details all the complete and tested routes available in the controllers folder, how to access them, what data they expect to receive in the requests sent to them, and what data you should expect in the response from that route.

Contents

Route Group 1

Note: It is recommended to group your routes by functionality, both in your file structure and in your documentation. For example if you have a users directory and an admin directory, and each of those directories has their own sub directories, write out the documentation in the same layout. This way the flow of your documentation matches the flow of your system architecture, making it a lot easier to read.

  • GET Route Map Template:
    Request Requirements: ""
    Expected Response: ""
    Method: GET
    URL: ""
    Example: ""

  • POST Route Map Template:
    Request Requirements: ""
    Expected Response: ""
    Method: POST
    URL: ""
    Example: ""

  • PUT Route Map Template:
    Request Requirements:
    Expected Response: ""
    Method: PUT
    URL: ""
    Example: ""

  • DELETE Route Map Template:
    Request Requirements: ""
    Expected Response: ""
    Method: DELETE
    URL: ""
    Example: ""

Route Group 2

  • GET Route Map Template:
    Request Requirements: ""
    Expected Response: ""
    Method: GET
    URL: ""
    Example: ""

  • POST Route Map Template:
    Request Requirements: ""
    Expected Response: ""
    Method: POST
    URL: ""
    Example: ""

  • PUT Route Map Template:
    Request Requirements:
    Expected Response: ""
    Method: PUT
    URL: ""
    Example: ""

  • DELETE Route Map Template:
    Request Requirements: ""
    Expected Response: ""
    Method: DELETE
    URL: ""
    Example: ""

Route Group 3

  • GET Route Map Template:
    Request Requirements: ""
    Expected Response: ""
    Method: GET
    URL: ""
    Example: ""

  • POST Route Map Template:
    Request Requirements: ""
    Expected Response: ""
    Method: POST
    URL: ""
    Example: ""

  • PUT Route Map Template:
    Request Requirements:
    Expected Response: ""
    Method: PUT
    URL: ""
    Example: ""

  • DELETE Route Map Template:
    Request Requirements: ""
    Expected Response: ""
    Method: DELETE
    URL: ""
    Example: ""

Route Group 4

  • GET Route Map Template:
    Request Requirements: ""
    Expected Response: ""
    Method: GET
    URL: ""
    Example: ""

  • POST Route Map Template:
    Request Requirements: ""
    Expected Response: ""
    Method: POST
    URL: ""
    Example: ""

  • PUT Route Map Template:
    Request Requirements:
    Expected Response: ""
    Method: PUT
    URL: ""
    Example: ""

  • DELETE Route Map Template:
    Request Requirements: ""
    Expected Response: ""
    Method: DELETE
    URL: ""
    Example: ""

Models Information

Here is where you will do something similar for the models. if you are documenting a SQL based API then it is very important to document what models are related to one another and in what ways to avoid confusion and annoying errors.

If you you are using a NoSQL solution it is advisable to provide a brief overview of what models are available, what schemas are defined(in any), if any relationships exist between those models, describe any validations you have set up, where you set them up, why you have them, and if any parameters are required be sure to emphasize them.

Server Information

If there are is already a server set up that contributors can connect to, describe your rules for contribution, naming conventions, data structure requirements, and how to request access if applicable.

If this there is not a server set up for someone to connect to and instead you expect people to clone the repository put basic server set up instructions here and in the readme.

About The Author

This is where you put your information. For example:

Author: Vincent Teune
GitHub: https://github.com/cobalt88
Email: [email protected]
Last Updated: June 2022

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