DEV Community

Cover image for Awesome README
Walter Nascimento
Walter Nascimento

Posted on

Awesome README

#readme #githunt #project #awesome

Clique aqui para ler em português

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.

Logo

If the system already has a defined logo, we start with it

![Logo](https://via.placeholder.com/150x150)
Enter fullscreen mode Exit fullscreen mode

Title

Leave a title for your project, if you don’t have a good name, you can put the project name.

# title
Enter fullscreen mode Exit fullscreen mode

Badge

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)
Enter fullscreen mode Exit fullscreen mode

Note: if you want to create your own, https://shields.io/ is a great tool

Menu

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)
Enter fullscreen mode Exit fullscreen mode

if the menu is too big change from horizontal to vertical.

## :bookmark_tabs: Menu

* [Overview](#overview)
* [Doc](#doc)
Enter fullscreen mode Exit fullscreen mode

Note: Insert README topics in links to facilitate reader navigation

Overview

Here you should give a quick description of what the system does.

## :scroll: Overview
Brief description of the project.
Enter fullscreen mode Exit fullscreen mode

Screenshot

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)
Enter fullscreen mode Exit fullscreen mode

Note: A gif showing the project is very useful.

Demo

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 | admin@mail.com | 123      |
Enter fullscreen mode Exit fullscreen mode

Documentation

If your system has documentation, leave a link to it here.

## :blue_book: Documentation

Documentation lives at readthedocs.org
Enter fullscreen mode Exit fullscreen mode

Requirements

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/)
Enter fullscreen mode Exit fullscreen mode

Installation and usage

Here you describe how your system should run for it to work properly

## Installation and usage


git clone https://github.com/<user>/<project>
Enter fullscreen mode Exit fullscreen mode

Note: Put a step by step to run your application.

Tests

Put a step by step to run the tests

### Tests

$ npm run test
Enter fullscreen mode Exit fullscreen mode

Dependencies and libs

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/)
Enter fullscreen mode Exit fullscreen mode

Folder Structure

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
Enter fullscreen mode Exit fullscreen mode

Note: If you use linux and want to display something like this the tree program is very good sudo apt install tree -y

Release History

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
Enter fullscreen mode Exit fullscreen mode

Contributing

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
Enter fullscreen mode Exit fullscreen mode

Tasks

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
Enter fullscreen mode Exit fullscreen mode

Authors

If you want to identify the project’s authors, this is the place

## :smiley_cat: Authors

- [@walternascimentobarroso](https://walternascimentobarroso.github.io/)
Enter fullscreen mode Exit fullscreen mode

License

Finally add the type of license your project has.

## :memo: License

The [MIT License]() (MIT)
Enter fullscreen mode Exit fullscreen mode

Template

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

https://readme.so/
https://github.com/kefranabg/readme-md-generator#readme

For other examples see the link below:

https://github.com/matiassingers/awesome-readme

Thanks for reading!

If you have any questions, complaints or tips, you can leave them here in the comments. I will be happy to answer!

😊😊See you! 😊😊

Top comments (0)

Read next

cduarte3 profile image

Lab 6 - Formatting and Linting

Christian Duarte -

nlea profile image

Handling Asynchronous Tasks in Cloudflare Workers – Part 1: Essentials for a Single Worker

Nele Lea -

vaishvi2811 profile image

Kickstarting Open Source with Hacktober!

vaishvi2811 -

mpalhutchinson profile image

Week 9: Lab 6: Static Analysis Tooling

mpa-LHutchinson -