Creating of Readme file
This gives suggestions and templates for a good README.
Kindly choose which sections apply to yours as every project or preference is different
Name
Here You Choose a self-explaining name for your project.
Description
Describe to people what your project is all about and what specifically it can do.
Provide context and add Name_links to any reference visitors might be unfamiliar with.
List the features of the project.
Kindly mention as well if there are different versions of the project.
Visuals
Add visual like screenshots, gif or video if your project requires it for better description.
Use tools like ttygif or Asciinema to make things easier for you.
Requirements
List all your requirements here especially
if your project only runs in a specific context like a particular programming language version or operating system or
has dependencies that have to be installed manually.
Sample:
- Windows 7, 8.1, 10
- Python version 3.6 or 3.7
Installation
A step by step series of examples that tell you how to get a development env running
Say what the step will be
Give the example
And repeat
until finished
Sample:
-
clone this repository.
-
create a virtual environment with python 3.x for the project
- Click here to learn how to create virtual environment for python project
-
Run the following command to install the packages in the requirements.
pip install -r requirements.txtor in case you are not using virtual environment and have multiple python versions installed.
pip3 install -r requirements.txt
Consider the possibility that whoever is reading your README is a novice and would like more guidance.
Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible.
Usage
Use examples liberally, and show the expected output if you can.
Like with an example of getting some data out of the system or using it for a little demo
Sample:
import foobar
foobar.pluralize('word') # returns 'words'
foobar.pluralize('goose') # returns 'geese'
foobar.singularize('phenomena') # returns 'phenomenon'Running the tests
Explain how to run the automated tests for this system
sample:
python manage.py testBreak down into end to end tests
Explain what these tests test and why
Give an example
And coding style tests
Explain what these tests test and why
Give an example
Deployment
Add additional notes about how to deploy this on a live system
Support
Tell people who and where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
Roadmap
List your ideas for future releases here.
Contributing
State here if you are open to contributions and also state your requirements for accepting the contributions
For people who would want to make contribute or make changes to your project, it's helpful to have some documentation on how to get started.
Perhaps there is a script that they should run or some environment variables that they need to set.
Make these steps explicit. These instructions could also be useful to your future self.
Sample:
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
Authors and acknowledgment
Show your appreciation to those who have contributed to the project.
Sample:
- hayhitee - Initial work - hayhitee
See also the list of contributors who participated in this project.
License
For open source projects, state the license.
Sample:
This project is licensed under the MIT License - see the LICENSE.md file for details
Project status
if the project development has slowed down or stopped completely, state at the top of the README. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going
If you need maintainers, kindly make an explicit request as well.