25
Awesome README
When entering a project, before looking at code the first information we see is what’s in the README, so nothing more fair than making a spectacular README.
If the system already has a defined logo, we start with it
![Logo](https://via.placeholder.com/150x150)
Leave a title for your project, if you don’t have a good name, you can put the project name.
# title
The badges, besides making it more elegant, help us with quick information so if possible add it to your project, an example would be the travis badge that informs you if you passed the test or not
[![Build Status](https://travis-ci.org/walternascimentobarroso/walternascimentobarroso.github.io.svg?branch=master)](https://travis-ci.org/walternascimentobarroso/walternascimentobarroso.github.io)
Note: if you want to create your own, https://shields.io/ is a great tool
By leaving it very descriptive, the README ends up getting too extensive, so as not to generate a tiring reading, it is interesting to have a small menu.
[Overview](#overview)
•
[Doc](#doc)
•
[Demo](#demo)
if the menu is too big change from horizontal to vertical.
## :bookmark_tabs: Menu
* [Overview](#overview)
* [Doc](#doc)
Note: Insert README topics in links to facilitate reader navigation
Here you should give a quick description of what the system does.
## :scroll: Overview
Brief description of the project.
Not everyone has time to check and run the project, the ideal is to have some screenshots of the project right at the start
## :rice_scene: Screenshot
![Logo](https://via.placeholder.com/750x500)
Note: A gif showing the project is very useful.
Now comes one of the most important parts, the demo, if your project is already published and you have a way to test it without having to download the project, leave the link for quick access here, and if you need to login, leave the data here too.
## :dvd: Demo
Lorem ipsum dolor sit amet consectetur, adipisicing elit.
| url | login | password |
| ------------------------ | -------------- | -------- |
| http://exemplo.com/admin | [email protected] | 123 |
If your system has documentation, leave a link to it here.
## :blue_book: Documentation
Documentation lives at readthedocs.org
If you want them to use your system, leave the necessary prerequisites described here, this way you avoid after downloading having to go through all the files and check which items are needed.
## :heavy_exclamation_mark: Requirements
* [Node](https://nodejs.org/en/download/)
* [PHP](https://php.net/)
Here you describe how your system should run for it to work properly
## Installation and usage
git clone https://github.com/<user>/<project>
Note: Put a step by step to run your application.
Put a step by step to run the tests
### Tests
$ npm run test
Some like to list each lib used, if you want here is a good place
### Dependencies and libs
- [React](https://pt-br.reactjs.org/docs/create-a-new-react-app.html)
- [React PDF](https://react-pdf.org/)
If the project has a unique folder organization it is useful to make this information explicit.
### Folder Structure
.
├── src # Project source code
├── doc # Doc for the project
├── .gitignore
├── LICENSE
└── README.md
Note: If you use linux and want to display something like this the tree program is very good sudo apt install tree -y
If it’s a big project with a lot of improvements already made, it’s nice to have a changelog
- 0.2.0
- CHANGE: Remove function
- ADD: Add init()
- 0.1.1
- FIX: Crash when calling baz()
- 0.1.0
- CHANGE: Rename foo() to bar()
- 0.0.1
- Init the project
Leave a simple way how to contribute to your project
1. Fork it (https://github.com/yourname/yourproject/fork)
2. Create your feature branch (git checkout -b feature/fooBar)
3. Commit your changes (git commit -am ‘Add some fooBar’)
4. Push to the branch (git push origin feature/fooBar)
5. Create a new Pull Request
If so, list tasks/features that still need to be implemented in your application
## :bell: Tasks
- [ ] Task 1
- [x] Task 2
- [x] Task 3
- [ ] Task 4
If you want to identify the project’s authors, this is the place
## :smiley_cat: Authors
- [@walternascimentobarroso](https://walternascimentobarroso.github.io/)
Finally add the type of license your project has.
## :memo: License
The [MIT License]() (MIT)
To use the full template see the link:
Notes:
- All information is optional, it is not mandatory to use everything, but the more information the better ;)
- As markdown does not have native css adjustment, it is necessary to use some old tags and attributes to simulate a more elegant layout
Extras
Some tools to create your readme
For other examples see the link below:
If you have any questions, complaints or tips, you can leave them here in the comments. I will be happy to answer!
😊😊See you! 😊😊
25