A Guide to Building Professional README Files.
A README document is a text file that describes your project, it's the first file most developers will read when visiting your repository. It should help other developers understand your code, how to use it, and answer any questions they may have.
When you're first starting out, your first project's README might say something like 'My to-do list project'. This lack of details is normal for anyone starting out, but if you master the syntax and principles of a good README, your project will look exponentially better. You will notice that most frameworks and libraries will have excellent READMEs that give you information on installation, code snippets, usage, features, contact info, contributing, technologies. You can see an example here. And here is a repository that lists some great READMEs with the excellent format we are looking for. An informative README inside your Github repository is crucial to any project. Learning how to write an effective one is a skill all developers should know.
The template
Here is a layout to use for your projects that will take them from zero to hero!
About The Project
First, give a description of the project to give the user a clear understanding of what you have built and why you have built it.
Features
Second, list out the features and benefits. This may be features like dark mode, animations, modals, and authentication. These are the highlights of the project, impress the reader with your awesome features!
Built With
Third, add a section that says what technologies you used in your project. Include frontend frameworks, major libraries, and databases. Some popular examples may be Bootstrap, React, and firebase.
API Reference
Credit the APIs that were used in your project and possibly basics on how to use them.
Getting Started
In this section explain the installation and setup instructions so the reader can set up the project locally.
Prerequisites
Tell the reader what packages or software they need in order to use your project and how to install them, this is commonly npm
Installation
Show how to clone the project into their local machine and install the packages.
Contributing
Contributions can create opportunities to work with amazing developers and grow a project into a masterpiece. Explain how the reader should contribute. The steps include forking the project, creating and committing your changes, pushing to the branch, and creating a pull request.
License
Tell the reader about licenses
Contact
Contact information
Acknowledgments
Here list out resources that should be credited for helping you create your impressive project
And that's it for structuring your README, thank you to Othneildrew for this awesome template! Please check out the repo for a clear example and show him some love!
Now lets move on to syntax inside our Github README file.
Syntax
Understanding this syntax is essential to creating a README. The reader will not be able to differentiate main topics, lists, images, links, or really anything. The file will look like an essay, not a reference to the project like it's supposed to.
Headings
Use # for different headings. The more hash symbols you use, the smaller the heading will be. One hash is an h1 element, two hashes is an h2, etc.. for example:
# Heading 1
## Heading 2
#### Heading 4
Styling text
Bold : or | **This is bold text** | This is bold text
Italic : or | *This text is italicized* I | This text is italicized
Strikethrough : ~~ ~~ | ~~This was mistaken text~~
Bold and nested italic : **This text is _super_ important** | This text is super important
All bold and italic : | ***All this text is important*** | All this text is important
Quoting text
This text is not a quote
use > This is a famous quote
This text is actually a famous quote
Writing code snippets
Put your code snippet inside of three backticks, one at the start and one at the end.
Example: ` buttonArr.map((button) => { return (
(Sandwiched between 3 backticks ```) Returns:
buttonArr.map((button) => {
return (
<div className='myBtn'>{button.text}</div>
)
})
Links
Add your link by wrapping the link text in brackets [ ] then adding the link in parathesis ( )
Example:
This is my [LINK](https://google.com)
Returns:
This is my LINK
Images
Add a ! and wrap alt text inside of brackets [ ] and the src into parathesis ( )
Example:
Returns:
Lists
You can make an unordered list with hyphens -
Example:
- Item 1
- Item 2
- Item 3
Returns:
- Item 1
- Item 2
- Item 3
You can make an ordered list with hyphens numbers
Example:
1. Item 1
2. Item 2
3. Item 3
Returns:
- Item 1
- Item 2
- Item 3
Task lists
Use brackets [ ] to show checkboxes, add an x inside of the brackets to show a completed checkbox [x]
Example:
- [x] Work
- [ ] Clean up
- [ ] Go shopping
Returns:
- [x] Work
- [ ] Clean up
- [ ] Go shopping
Emojis
To use emojis type :EMOJICODE:
Example:
:U+1F601:
:U+2764:
:U+1F44C:
Returns:
😁 ❤ 👌
Highlights
Put a word or syntax inside of a single backtick, this will create a highlight like this which you have seen throughout this article.
Example:
This is my `highlighted word` that you can see
Returns:
This is my highlighted word that you can see
Comments
Exclude information about code with the syntax:
<!-- This content will not appear in the rendered Markdown -->
And now you know how to complete your project with an awesome README guide. You learned how to structure your data and how to write 'Github syntax' which makes your file readable, it is a README file after all!
Conclusion
In this article we covered:
- What a README file is
- Why you need a README file
- How to structure your README
- How to write syntax for the README
Wow did I say README enough in this article 😅
Thank you for reading my first blog article. I decided to do a simple topic as this is my first blog to get a feel for Hashnode. I am very excited about starting my blog journey, if you are interested in reading articles from a newbie Dev that's trying to make it out here in the tech world, follow me! For the template, all credit goes to Othneildrew, he has helped me structure my README files in a way that makes them look clean and professional. Thank you to the writers at Github I used the Github docs to create the Syntax section.