Next, describe the project here. The project title should be descriptive and help people understand what the main goal and purpose of the project is in one sentence or less. The project description should explain and show what the application does, why it uses the technology it does, and some of the challenges it has faced and features it will implement in the future.
To avoid information overload, use the first three to five sentences of the README to give a brief introduction to the project. In addition, you can briefly mention and link to topics from the following sections of the project's README, where readers should be able to understand the what, why, and how of the project in detail. Use some of the guiding questions below:
- What was your motivation?
- Why did you create this project?
- What problem does it solve?
- What did you learn?
- What makes your project unique?
Here's an example of an introduction:
- Table of contents might be useful when the README is very long
- It can ease the navigation around the README for readers
- If the project requires that a user needs to install or run locally in a machine, you should include the steps required to install your project and also the required dependencies if any
- Provide a step-by-step description of how to get the development environment set and running
- Provide instructions and examples so users/contributors can use the project
- This will make it easy for them in case they encounter a problem – they will always have a place to reference what is expected
- You can also make use of visual aids by including materials like screenshots to show examples of the running project and also the structure and design principles used in your project
- If your project will require authentication like passwords or usernames, this is a good section to include the credentials