How to Write a Good README File for Your GitHub Project
When I was first introduced to GitHub, I had no idea what it was or what it could do. Between you and me, I created the account because I was told every developer should have one where they push their code.
For the longest time as a beginner I did nothing with my account. But then, becuase of my passion in tech, I started following other developers and checking out their work on GitHub. And I noticed something they had in common: they all had cool projects and contributed to open source, but their projects also had detailed README files .
So my interest in what a README was grew, and I decided to try and add one in my projects, too. I won't lie – I did it in a hurry without any knowledge of how it should be done. And honestly it wasn't great at all. Check it out HERE .
And that was how it stayed for a period of time. But with practice and continuous learning I was able to change to some better documentation like THIS , which improved engagement with the project and helped other devs get involved.
It is also important to note that a good README will help you stand out among the large crowd of developers who put their work on GitHub.
In this article, we'll learn more about what a README file is and how to write one. First let's understand what we mean by a README file.
What is a README File?
In simple words, we can describe a README file as a guide that gives users a detailed description of a project you have worked on.
It can also be described as documentation with guidelines on how to use a project. Usually it will have instructions on how to install and run the project.
It is essential for you as a developer to know how to document your project by writing a README because:
- It is the first file a person will see when they encounter your project, so it should be fairly brief but detailed.
- It will make your project standout from a bunch of others. Also be sure your project is good too.
- It will help you focus on what your project needs to deliver and how.
- It will improve your writing skills, just as Friedrich Nietzsche said:
A good writer possesses not only his own spirit but also the spirit of his friends.
While working on a project, keep in mind that you will need other developers to understand your code and what it does. So accompanying it with an extra guide will be really helpful.
For instance, my earlier shared example of my first project does not have a good README. And even though the project was amazing, it would've been hard for a beginner to understand exactly what was expected when they cloned my repo. Who knows maybe it could've even been a coded virus.
With a project like this on GitHub, no matter how amazing it is, other devs won't be eager to work on it and try to figure it out without a good README.
Now, have a look at this project . Here, you are able to understand what the project does, what it entails, and how to get started if you need to use or want to contribute to the project.
You see, that's how powerful a well written README is and how it can change you project.
So, let's get started on how to write one for you too.
How to Write a Good README – a Step by Step Guide
A very important thing to note is that there's not one right way to structure a good README. But there is one very wrong way, and that is to not include a README at all.
From research and studying various README files, for sure there are some best practices that I have found. And that's what I will be sharing. As I usually tell my self:
Every day is a learning day.
So as you progress and advance in your career, you will develop your own ideas about what makes a good README and how to improve on it. Perhaps you'll even come up with your own unique guide.
Before we get started, it is also important to note that when you're writing your project's README, it should be able to answer the what , why , and the how of the project.
Here are some guide questions that will help you out:
- What was your motivation?
- Why did you build this project?
- What problem does it solve?
- What did you learn?
- What makes your project stand out? If your project has a lot of features, consider adding a "Features" section and listing them here.
What to Include in your README
1. project's title.
This is the name of the project. It describes the whole project in one sentence, and helps people understand what the main goal and aim of the project is.
2. Project Description
This is an important component of your project that many new developers often overlook.
Your description is an extremely important aspect of your project. A well-crafted description allows you to show off your work to other developers as well as potential employers.
The quality of a README description often differentiates a good project from a bad project. A good one takes advantage of the opportunity to explain and showcase:
- What your application does,
- Why you used the technologies you used,
- Some of the challenges you faced and features you hope to implement in the future.
3. Table of Contents (Optional)
If your README is very long, you might want to add a table of contents to make it easy for users to navigate to different sections easily. It will make it easier for readers to move around the project with ease.
4. How to Install and Run the Project
If you are working on a project that a user needs to install or run locally in a machine like a "POS", 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.
5. How to Use the Project
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.
Also if your project will require authentication like passwords or usernames, this is a good section to include the credentials.
6. Include Credits
If you worked on the project as a team or an organization, list your collaborators/team members. You should also include links to their GitHub profiles and social media too.
Also, if you followed tutorials or referenced a certain material that might help the user to build that particular project, include links to those here as well.
This is just a way to show your appreciation and also to help others get a first hand copy of the project.
7. Add a License
For most README files, this is usually considered the last part. It lets other developers know what they can and cannot do with your project.
We have different types of licenses depending on the kind of project you are working on. Depending on the one you will choose it will determine the contributions your project gets.
The most common one is the GPL License which allows other to make modification to your code and use it for commercial purposes. If you need help choosing a license, use check out this link: https://choosealicense.com/
Up to this point what we have covered are the minimum requirements for a good README. But you might also want to consider adding the following sections to make it more eye catching and interactive.
Additional README Sections
Badges aren't necessary, but using them is a simple way of letting other developers know that you know what you're doing.
Having this section can also be helpful to help link to important tools and also show some simple stats about your project like the number of forks, contributors, open issues etc...
Below is a screenshot from one of my projects that shows how you can make use of badges:
The good thing about this section is that it automatically updates it self.
Don't know where to get them from? Check out the badges hosted by shields.io . They have a ton of badges to help you get started. You may not understand what they all represent now, but you will in time.
9. How to Contribute to the Project
This mostly will be useful if you are developing an open-source project that you will need other developers to contribute to. You will want to add guidelines to let them know how they can contribute to your project.
Also it is important to make sure that the licence you choose for an open-source projects is correct to avoid future conflicts. And adding contribution guidelines will play a big role.
Some of the most common guidelines include the Contributor Covenant and the Contributing guide . Thes docs will give you the help you need when setting rules for your project.
10. Include Tests
Go the extra mile and write tests for your application. Then provide code examples and how to run them.
This will help show that you are certain and confident that your project will work without any challenges, which will give other people confidence in it, too
Extra points
Here are a few extra points to note when you're writing your README:
- Keep it up-to-date - It is a good practise to make sure your file is always up-to-date. In case there are changes make sure to update the file where necessary.
- Pick a language - We all come from different zones and we all speak different languages. But this does not mean you need to translate your code into vernacular. Writing your README in English will work since English is a globally accepted language. You might want to use a translator tool here if your target audience isn't familiar with English.
There you have it, everything you need to improve your README files, or even get you started with writing your first one.
At this point I am confident that you are in a position to add an interactive and inforamative guide to your next project or even an existing one and make your project standout.
There are many tools which you can also use to automatically generate a README for your project, but it's always a good practice to try it on your own before moving to automation. In case you want to check them out, they include:
- Make a README
- README Generator
If you have read this far I really appreciate it. If you enjoyed this article and found it helpful, please share it so you can help another developer improve their projects.
I would love to see your newly crafted README file. Be sure to share a link with me via any of the links below:
Connect With me at Twitter | YouTube | LinkedIn | GitHub
Do share your valuable opinion, I appreciate your honest feedback!
Enjoy Coding ❤
Growing Developer || Python & Open-Source ❤ || Tech Enthusiasts & Writer ✍ "Every day is a learning Day"
If you read this far, tweet to the author to show them you care. Tweet a thanks
Learn to code for free. freeCodeCamp's open source curriculum has helped more than 40,000 people get jobs as developers. Get started
Make a README
Because no one can read your mind ( yet )
What is it?
A README is a text file that introduces and explains a project. It contains information that is commonly required to understand what the project is about.
Why should I make it?
It's an easy way to answer questions that your audience will likely have regarding how to install and use your project and also how to collaborate with you.
Who should make it?
Anyone who is working on a programming project, especially if you want others to use it or contribute.
When should I make it?
Definitely before you show a project to other people or make it public. You might want to get into the habit of making it the first file you create in a new project.
Where should I put it?
In the top level directory of the project. This is where someone who is new to your project will start out. Code hosting services such as GitHub , Bitbucket , and GitLab will also look for your README and display it along with the list of files and directories in your project.
How should I make it?
While READMEs can be written in any text file format, the most common one that is used nowadays is Markdown . It allows you to add some lightweight formatting. You can learn more about it at the CommonMark website , which also has a helpful reference guide and an interactive tutorial .
Some other formats that you might see are plain text , reStructuredText (common in Python projects), and Textile .
You can use any text editor. There are plugins for many editors (e.g. Atom , Emacs , Sublime Text , Vim , and Visual Studio Code ) that allow you to preview Markdown while you are editing it.
You can also use a dedicated Markdown editor like Typora or an online one like StackEdit or Dillinger . You can even use the editable template below.
Markdown Input (editable)
Foobar is a Python library for dealing with word pluralization.
Installation
Use the package manager pip to install foobar.
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
Suggestions for a good README
Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
Choose a self-explaining name for your project.
Description
Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
Within a particular ecosystem, there may be a common way of installing things, such as using Yarn , NuGet , or Homebrew . However, 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. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
If you have ideas for releases in the future, it is a good idea to list them in the README.
State if you are open to contributions and what your requirements are for accepting them.
For people who want to 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.
You can also document commands to lint the code or run tests . These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
Authors and acknowledgment
Show your appreciation to those who have contributed to the project.
For open source projects, say how it is licensed .
Project status
If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
Is there a standard README format?
Not all of the suggestions here will make sense for every project, so it's really up to the developers what information should be included in the README.
What are some other thoughts on writing READMEs?
Check out Awesome README for a list of more resources.
What should the README file be named?
README.md (or a different file extension if you choose to use a non-Markdown file format). It is traditionally uppercase so that it is more prominent, but it's not a big deal if you think it looks better lowercase .
What if I disagree with something, want to make a change, or have any other feedback?
Please don't hesitate to open an issue or pull request . You can also send me a message on Twitter .
Mind reading?
Scientists and companies like Facebook and Neuralink (presumably) are working on it. Perhaps in the future, you'll be able to attach a copy of your thoughts and/or consciousness to your projects. In the meantime, please make READMEs.
What's next?
If your project is open source , it's important to include a license . You can use this website to help you pick one.
Make a README is inspired by Keep a Changelog . A changelog is another file that is very useful for programming projects.
More Documentation
A README is a crucial but basic way of documenting your project. While every project should at least have a README, more involved ones can also benefit from a wiki or a dedicated documentation website. GitHub , Bitbucket , and GitLab all support maintaining a wiki alongside your project, and here are some tools and services that can help you generate a documentation website:
- Read the Docs
Just having a "Contributing" section in your README is a good start. Another approach is to split off your guidelines into their own file ( CONTRIBUTING.md ). If you use GitHub and have this file, then anyone who creates an issue or opens a pull request will get a link to it.
You can also create an issue template and a pull request template . These files give your users and collaborators templates to fill in with the information that you'll need to properly respond. This helps to avoid situations like getting very vague issues. Both GitHub and GitLab will use the templates automatically.
DEV Community
Posted on Oct 17, 2022
How to write a good README
The README file is the one-stop documentation file . Usually, it is not only the first file any person will read when reaching your project for the first time, but also it is the key document for your recurring visitors.
Why is important the README?
A few weeks back I had to install an open source project in my computer. It was the first time I was interacting with the project and experience was horrible, something that should have taken me no more than one or two hours to do, took me two days, and the main reason it took me so long was because it had a README file that could be improved to help developers new to the project to have a better first interaction.
Integrate and use open source solutions, library or tools in our own projects is the day-to-day for many developers, and the starting point for this tasks is arguably the README file. So a good README, is as indispensable for an open source project as it is the quality of the code.
Who is your audience?
Before digging into what are good contents and how to write a README file, let's dig into who's going to read this document.
To write a good README one of the keys is to think about the reader . Who is this file for? Who is your audience? In this regard, I like to classify them in three categories.
End users . They are the actual users of your application. These may also be business analysts that are seeking for a solution. They may not have a strong technical knowledge and they are more worried about the functional aspects of your solution and not so much about the technology implementation.
Technical users . These are people that have technical background and are going to install or setup the project in their own environment. You can consider them also as some kind of integrators. They are going to take your project and integrate it into the project they are working on. They care about the technical aspects, but just as a user, that is, they do not care too much about how it is implemented, but more about the functionality offered. For example, if your project exposes an API or it is a library, they want to use the API/library, but they are not interested in learning about all the implementation details.
Note that depending on the project type, sometimes the end user and the technical user may be the same target audience. For example, if your project is a Javascript library such as React JS, your end user is also, most of the time, the technical user, a developer. However, if your repository is an iOs application, your end user - someone with an iPhone who will use App Store - is not necessarily the same as your technical user - someone that wants to install the app using Xcode.
Contributors . They are people you are going to interact with somewhat because they go one step beyond in their involvement with your project. For example, a contributor can be a technical user that needs some support to install the solution, someone that wants to report a bug or suggest a new feature, someone that wants to submit a pull request with an enhancement, or someone that wants to support economically the project. As you can see, this is the most diverse group, but including all of them in one group keeps things simple.
README format and writing style
Although README files are plain text files because most of the source code hostings such as Github , GitLab or Azure Repos support the Markdown format . Because of that, most of the README files you will see in the wild are written using the Markdown syntax .
This text format is pretty simple but rich enough for having a nice output. It supports headings, bold, italic, bulleted lists, numbered lists, code blocks, links, etc. Indeed, behind the scenes, this blog post is written in Markdown too.
Quick example of Markdown:
Based on the axiom " people don't read, they scan " , the proper use of Markdown will allow you to give the document some visual structure and help users scan the contents of the file.
By setting a structure (using headers, lists, paragraphs) you are helping you users to quickly find the information they are seeking.
For example, a developer found your project while he was in the subway coming back home, because he was on the phone he starred it and a few days later came back to install it. Some weeks later he found a bug, and he wanted to report it. By adding headings - that is structure - to your README - he will have it much easier to find the particular section he is interested in.
Furthermore, to adapt the text to the way we read online , i.e. scanning, searching for key words, etcetera, you can follow some basic principles for writing for the web , like the following:
Use short paragraphs . Using around 3 to 5 lines is a good rule of thumb. Each paragraph should have only one concept. This will help scanning.
Use bulleted or numbered list instead of comma separated lists. This list of basic rules is na example. Again this helps scanning.
Never ever use click here for a link, use some meaningful text instead. Among other reasons, using click here forces users to read the context around the link, whereas a more appropriate text, will explain the reader why you shall never use click here .
Highlight key words or sentences paragraphs with bold. Avoid using underline, because it may be confused with a link.
Start with the most important information in each paragraph. Use inverted pyramid structure ** in your writing. Start with the content that is most important to your audience, and then provide additional details.
README contents
Ok, now that we know who are we writing for and good practices about how to give structure and form to the file, let's see some suggested contents for the README.
The structure presented here follows the natural way of interacting with your project:
- First we will shortly explain what it is the project about ,
- then, we will continue on how to install and how to get started with it and,
- finally, we will provide the reader how to get involved , how to collaborate.
This structure follows the level of involvement with your project it is expected from each of the categories of users we have presented. End user just wants to learn about the project.
Note that some sections may not fit your project in particular or you may prefer to label them differently, but in any case the three level structure above will apply for sure.
Let's start with the sections:
Here you want to briefly introduce your project . It should not be more than two or three paragraphs. Think what you need to tell to someone that is looking at your project for the first time. The main audience for this section are your end users .
After this short intro, you may include links to the website, wiki page with further explanation and/or a demo for those that are interested in getting more about your project.
Finally, you may want to list some of the technologies, frameworks that you are using or supporting (if it is not obvious). This piece of info is interesting for the technical users that may need to evaluate if it fits the architecture of their project or organization.
Here is an example of the React JS project (in Markdown)
As you can see, first the project is showcased and at the end, you get a link to more info. In this case, the main audience are developers, and therefore end users and technical users are the same.
At this point, you got enough attention from the README reader, so he wants to go one step beyond and try it.
Here you have to expose the steps to install your stuff . For example for a NodeJS application, usually you will instruct something like:
Or for a python library
and so on so forth.
PRO Tip: In Markdown you can enclose code blocks with three apostrophes. If you add the name of the language after the first set of three apostrophes (for instance ruby , javascript , typescript , swift , bash ) when rendered, syntax highlighting will be applied.
For example:
Is rendered:
Note that in this case you are assuming that the reader has the package managers, npm or pip , installed on his system, which may not be the case. So, think about specifying the pre-requisites needed before attempting to install your project . Just providing a link to the install page of each pre-requirement may be a great help for your reader. In the NodeJS example above:
Usage / Getting started
Now that the reader has your project in his system, it is time to showcase the superpowers he can do now thanks to your stuff.
In getting started you can either include some basic instructions inline or point to a more rich documentation.
The goal is to guide the reader in what to do once he has just installed your project in his environment.
Documentation
In addition to the basic first steps/getting started the reader may want to dive into all the functionality of the project. It may depend on the kind of project:
- For an application it may describe how to use it, the options, how to set it up for different use cases.
- For a library, framework it may describe API, methods, classes, or some advanced examples.
Some additional documentation you may think about are:
- Deployment good practices. How to deploy it in a production environment.
- Security guidelines. How to harden any installation to avoid any cybersecurity issue.
- Troubleshooting.
Depending on how you structure your documentation and your README you may merge this section with the Getting started one.
Development
From now on, this and the following sections will be for the readers that get into the nitty-gritty of your project or that want to become an active member of the community. Within the classification of potential readers are the ones that we called the contributors.
This development section is for setting up the environment in dev mode . What are the tools that you need and how to run the project in debug mode, run the unit testing, etc.
Contributing
This section is for providing any additional information for the reader that wants to really contribute.
- How to report a bug
- Code of conduct
- Coding Style guide
- How to make a pull request (PR)
- How to get support
- How to make a donation
- How to contact for commercial support
You may want to add part of this documentation in a separate file. For example, GitHub allows you to set up the CODE_OF_CONDUCT.md and other files .
Acknowledgements
It is a good practice to acknowledge those who have been inspiration of your work (other repos, other projects) or mention those key contributors of the project, that is, those that have added new features, submitted pull requests, fixed bugs, etc.
The last section of the README typically is reserved for the copyright and license.
Though, at a first glance, you may think that this is not important, the truth is that it setting up a license is key as it helps other developers to understand the limits of the use of your software.
Here you have a list of open source licenses . You should have a rough idea of what each license means. Personally, I usually choose between GPL3 and MIT.
MIT is the simplest license one, more or less it says: you can do whatever you want with this piece of code. Do it at your own risk and do not suit me.
GPL , is a copyleft license . It is a more restrictive license than the MIT as it forces any contribution or customization of the code to be publicly released, as well as to be distributed under the same GPL license. It is less attractive for a commercial usage, but better for the overall community as any contribution reverts back to the community. For example the GNU/Linux kernel is distributed under this license.
In this section of the README, you don't need to add the whole text of the license, just the banner, but usually, you should include a copy of the whole license in the file LICENSE or LICENSE.md .
Extra balls
A couple of things that you can add to your project README are images and status badges.
As it was mentioned earlier, README files generally are written in Markdown. This language, allows you to link images within that will be displayed once the Markdown is rendered.
In particular there are two cases which this may be useful:
To make it look cooler. For example adding a logo at the beginning of the readme, makes it look good. It gives a good first impression.
Showcasing / Providing a demo. An image is 1,000 words worth. You can record a simple animated GIF and showcase key features of your project helping the reader to grasp what's your project about with less effort.
Status badges
Another "cool" thing you can add in your README file is a status badge. A status badge displays what is the status of a particular aspect of your repo, it can be if the unit testings are passing failing, if your pipelines are working, what is the latest version released, the code coverage, and a long etcetera.
It gives a snapshot to your visitors in a nutshell some indicators of the project.
You can check the badges/shields repo to add some badges to your project.
The only drawback of using images and the badges in the README is that they will not be rendered in a simple text editor, but you can ignore it as most of the time this file will be displayed either in the repo website or in a developer friendly editor which usually support Markdown rendering.
If you are working in an Open Source project, the README file is a key one-stop document that can boost the developer experience.
To write a good readme you need to keep in mind the types of audience that will read the file: end-users, technical users and contributors.
You should pay attention on how people read on the web , helping them to scan your README using Markdown, and the good practices for writing for the web such as short paragraphs, lists and the inverted pyramid writing schema.
The contents of the README should follow a structure that first introduces the project, then explains how install and use it and, finally, explains how to get involved in the project as contributor.
I hope you enjoyed the article. One final question. What is the best or your favorite README file?
Top comments (10)
Templates let you quickly answer FAQs or store snippets for re-use.
- Email [email protected]
- Location China
- Education Undergraduate
- Joined May 26, 2022
Nice tips! And I would always add a Built with block, displaying the tech stack I'm using for this project. Example here
- Joined Sep 9, 2020
Yeah, though I did not add it as a section itself, I mentioned it as something that could be added in the Overview. It is a useful piece of information to validate it is aligned with your tech stack / knowledge.
- Joined Dec 3, 2021
Good Post! Greetings from Argentina!
- Location Bihar, India
- Education Currently I am in 1st year.
- Work I am a college student of NIT Agartala.
- Joined Dec 4, 2021
I like it. Love form India.
- Location Germany
- Joined Jul 22, 2019
I love this, amazing post!
- Joined Aug 8, 2022
Great Article! It's gonna help me a lot!
- Joined Jun 10, 2020
Any README should: Start with WHY.
Here's an example where I did my best at a helpful README: github.com/amo13/spleeter-wrapper/
That's a good point. I am a fan of the golden circle of Simon Sinek
- Email [email protected]
- Location Hungary
- Work Fullstack developer
- Joined Jul 19, 2022
Nice article. Open-source is not just coding, these readme/docs can make a huge difference.
- Education Trinity Western University
- Work Student
- Joined Oct 24, 2022
Thanks for the tips!
Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink .
Hide child comments as well
For further actions, you may consider blocking this person and/or reporting abuse
- What's a billboard?
- Manage preferences
18 Useful Github Repositories Every Developer Should Bookmark
18 Useful GitHub repositories every developer should bookmark: everything from learning resources and roadmaps to best practices, system designs, and tools.
How to get Clone a private Github repo!?
عبدالله عياد | Abdullah Ayad - Dec 29 '22
Hacktoberfest 2022 shipping t-shirt
Holiq Ibrahim - Dec 27 '22
Fetching and Loading Data from Github
Ochwada Linda - Dec 29 '22
pyaction: A Docker container with Python, git, and the GitHub CLI
Vincent A. Cicirello - Dec 28 '22
Once suspended, merlos will not be able to comment or publish posts until their suspension is removed.
Once unsuspended, merlos will be able to comment and publish posts again.
Once unpublished, all posts by merlos will become hidden and only accessible to themselves.
If merlos is not suspended, they can still re-publish their posts from their dashboard.
Once unpublished, this post will become invisible to the public and only accessible to merlos.
They can still re-publish the post if they are not suspended.
Thanks for keeping DEV Community safe. Here is what you can do to flag merlos:
merlos consistently posts content that violates DEV Community's code of conduct because it is harassing, offensive or spammy.
Unflagging merlos will restore default visibility to their posts.
We're a place where coders share, stay up-to-date and grow their careers.
Nov 25, 2016
A Beginners Guide to writing a Kickass README ✍
Hey beginners,
Congrats on making your way to open source. It’s a great community.
It’s a bit confusing in the starting. How to contribute, where to contribute, issues, bugs, PR, PR, PR!
Don’t worry, as you get yourself involved in open source you’ll learn it all.
But today I’d like to give you all some advice which I never received when I started my open source journey.
I started contributing to open source and putting all my tiny side projects on GitHub a while ago. Back then I didn’t know about the README part. Time passed and I started following some kickass developers . No doubt they all had amazing projects but the one most common thing was, all their projects had awesome README and that’s how I came to know about the importance of a good README.
STOP!! I’m not interested in reading about your open source journey. Just tell me about how to write a good README.
Cool. So here you go —
Before you start putting your awesome projects on GitHub, I want you to go and read about Readme Driven Development first.
Why should I care about a README?
Open source community is growing rapidly . Developers release new open-source projects on GitHub every day. As a result, it’s becoming more and more difficult to get your own project to stand out from the sea of open-source software. However, you can do a few things to increase your chances of grabbing other developer’s attention. One effective and simple technique is putting up a nice-looking and helpful README file . Your README should be as good as your project. A great README file helps your project to stand out from the sea of open-source software on GitHub. A README is like the face of your project. It is the first file a person should read when encountering a source tree, and it should be written as a very brief and giving very basic introduction to the software.
A project without README is not so useful. Let’s take a look at this project , for instance.
No README, no description, no nothing. You won’t get any idea what this guy built, no matter how awesome it is.
Now let’s take a look at this project . The author has mentioned detailed and clear instructions about the project and hence easier for others to use and try it out.
A nice README is a good way to help people engage in the project as well. A project with nice README and screenshots will get the attention of users better since it’s a direct way to explain why this project matters, and why people should use and contribute to the project. Good README should also include enough details to help a new user get started, e.g. how to compile, how to install, and how to start integrating.
Ok. Enough talk. Show me how to write a good README then.
Now as you agree that README matters, I’ll tell you how to write one. It’s not so difficult. You just need to stick with some bullet points. Here are some of the points you should keep in mind while writing a README.
Formatting of README?
Now that you have taught yourself how and what to write in a README, let’s talk a bit about the styling of README aka formatting .
Formatting is an essential part of README. You can learn about how to format your README from here and here .
In the end, Keep in mind —
You don’t need to go full-bore Readme Driven Development, you don’t need to include all those bullet points , you don’t need to follow any particular process. But writing a good README will definitely improve your documentation skills which will make you a better developer.
You can check out some of the examples and resources which will help you in writing a good README.
akashnimare/foco
Stay focused with foco :rocket: [wip], sindresorhus/pageres, pageres - capture website screenshots, noffle/art-of-readme, art-of-readme - :love_letter: learn the art of writing quality readmes., matiassingers/awesome-readme, awesome-readme - a curated list of awesome readmes, dbader/readme-template, readme-template - readme.md template for your open-source project, jehna/readme-best-practices, readme-best-practices - best practices for writing a readme for your open source project, the most important code isn't code, documentation is the single most important change i've made to my coding style in the last year. i'm not talking about….
zachholman.com
That’s it. You’re ready to rock-n-roll in the open source world 😎
Thanks for reading. If you are just starting out your open source journey, you should checkout my other article about my development setup here . If you have any questions or need any help, feel free to contact me here @ meakaakka .
If you have enjoyed this article and would like to buy me a coffee ☕️ follow this 👇
More from Akash
Figuring it out
About Help Terms Privacy
Get the Medium app
Text to speech
Rita Łyczywek Ruby on Rails developer www.flynerd.pl
How to write a good README for your GitHub project?
Get to know why writing a good readme is important, and how to improve its legibility..
It is worth or even necessary to add a README file in every new project. Today we will focus on good practices of writing such a file - with a few examples, and a ready to use template.
What is a README file?
README (as the name suggests: "read me") is the first file one should read when starting a new project . It's a set of useful information about a project, and a kind of manual. A README text file appears in many various places and refers not only to programming. We will focus on a programmer's README, though.
example of README for a Bootstrap gem (Ruby On Rails)
Added README file on GitHub appears under the list of files in a repository.
If we work professionally or learn coding, many times we come across the public repositories. We use the libraries made available by other developers as an open source code or we make our contribution to a project, reporting/fixing bugs, and adding new functionalities. Certainly, we use these projects because they just come in handy, and offer a high quality solution. But would we use them if they lacked a user-friendly description, that is, a good README?
Rest assured - you will get to know the feeling of disappointment when finding a potential solution to all of your problems in a library or a project which description is poor, useless or isn't available whatsoever.
What's the use of writing a good README?
I think you can guess it already. A good README is for others to understand what our code includes, and why it's noteworthy . A README file is also essential to retreive a project - on GitHub but also in browsers (e.g. Google).
I am just learning so why should I be bothered about adding a README file? That code is just for me, after all, not for the whole community.
I doubt the code is just for you. And adding a README file is a good move.
README for Junior Devs
OK, now let's check why we should care for our README files since the first project!
Even if the code is just for you, possibly you will come back to it after a while. A good README enables you to relaunch a project - without wasting your time on recalling: What was it all about?
For a budding programmer, GitHub is a calling card . The projects on GitHub are most often our portfolio. When we're at a career stage without a considerable commercial experience or nice-looking non-profit projects, a presentation of our achievements in a form of repositories is one of the best way to get visible to the recruiters. A preparation of several demonstration projects we want to show off during the interview works the best.
If we are just learning and we drop our training projects there, let's pay attention to their good description. Even a non-technical recruiter will be able to recognize the technologies we touched, and check if it goes in line with a candidate's profile he's/she's looking for .
In Polish or in English?
Certainly, in English . Add a project description in English even if your project is in Polish language. The projects realized at the university might be treated as an exeption as they often demand a documentation in Polish. In every other case, describe your projects in English.
README.md - wait, what's it all about?
.md extension comes from a word: markdown . It's a markup language for text formatting. Maybe at first it isn't be obvious but markup has been created to make text creation easier . In HTML language, the most important heading goes with h1 tag. Similarily, we will have # before a heading in our document. We edit .md files in any text or code editor (Notepad, Sublime, Atom, CS, etc.).
You'll find out more on markdown usage on GitHub , and on dillinger.io you'll find an editor with a preview.
Writing a good README - newbies manual
Open a README.md. file in a new project.
Make sure the file always includes the following elements:
Titles and internal titles
- Introduction - the project's aim
Technologies
Consider also using additional elements such as:
Table of contents
Illustrations.
- Scope of functionalities
Examples of use
- Project status
Other information
That's a lot! There's not so much to say about my project!
There is - but you're not aware of that already.
A title should explain clearly what we have here, and it's usually a project's name - a H1 heading prefaced with # . If a project's name doesn't disclose its content, still it's worth to suggest what it is.
Moreover, the text should include the titles of sections, and - if necessary - the internal titles. To keep our README coherent, we write them similarly in every other document. In our README.md file, the headings should be written down with a multiple of # :
Introduction
Introduction is like a summary. It shouldn't be too long as we don't want to read an essay on a project. We should describe in an interesting manner what's the project aim, and what problems does a given application solve. Two or three sentences are enough in case of a small project.
If it's a training project, mention your incentive. Why did you want to create it? To learn a particular technology? Was it a hackathon project? Was it for a non-profit organization? Is it an application created to memorize the material from workshops or and online course? It's worth mentioning here, without a doubt.
Let's write down the languages we used, the libraries and its versions. For example:
- Bootstrap 3 or 4
- AngularJS 1.6 / Angular 2+/4/5/6
- Python 2.7 or 3.6
- Rails 4 or 5
Why? Firstly, it will be helpful when launching the project in the future. The versions of libraries change, and an inconspicuous change might cause many problems later on. It's good to know the version that has been used when our code was working exactly the way we wanted.
Another thing: recruitment. IT recruiters browse through their candidates' GitHub accounts . Even though they lack a technical knowledge to estimate the quality of solutions, they know the keywords related to their job offers. A description of used technologies might make you stand out among other candidates.
Let's assume there's a multitude of candidates for an internship, and a recruitment time is limited. CVs have been selected, there are two similar candidates, and a last available date in a calendar. The candidates' GitHub accounts include the same number of projects. One of them mentions the technologies in every project. A second candidate doesn't add README files or his/her projects are described poorly. What do you think, which candidate will be invited for an interview?
How to run a project? Does a project has minimum hardware requirements? We mentioned the libraries and their versions earlier. If necessary, technologies, launch, and hardware requirements can be merged together. But if we split it into two subsections, it's worth to focus here specifically on launching a project. When we have a website or application, it can concerned setting up a local environment, a link to GitHub pages or deployed application on Heroku. Do we need input data? If so, in what format?
Let's focus on other elements that can improve our README .
Table of contents comes in handy in case of extensive documentation. It can work as a simple list with the links to headings.
GitHub automatically adds id to headings according to the content inside a tag (spaces will become a sign "-"). Therefore, the links are constructed this way: https://github.com/user/repo-name#header-name . It enables to create a simple table of contents, e.g.:
And it will look like:
GitHub allows for graphics in README. A technical documentation doesn't need to be pretty but legible and understandable. The illustrations aren't necessary - nevertheless, they can aesthetical value to our project. You can show an application's logo, diagrams, schemes, exemplary screenshot. Maybe an illustrated manual is something you want?
Create a file in your repository, and add an image there. Use a file path to display it using:  . You can use the images from beyond you repository if they're publicly available - but there's always a risk that the owner of these sources would delete them from his/her domain, and they'll disappear from your documentation: 
Example: In my README file, I want to place a block schema that would illustrate how an algorithm works. I keep my schema.jpg file in a directory called images. To display it in my documentation, I will use a code:
Scope of functionalities
There's no always use in describing the scope of functionalities. For a website-visiting card or a simple application of to-do type, the list of functionalities is an excess of form.
On the other hand, a seemingly simple project such as to-do list can be extended with many interesting options we can be proud of: users register, recording and classifying the tasks according to date, adding commentaries to the tasks or data export to the files.
In case of reusable code or your own library, providing a manual how to use our project might be necessary. It can work as a fragment of code:
which will be displayed as:
The project status
It's worth to add a project status - especially if the project is still being developed. If it's our library, let's mention planned changes, direction of development or to emphasize we're done with its development.
Should we add information when our project was based on a tutorial or we got inspired with a given task? Yes, sure.
I don't get the doubts in that matter. There's nothing embarassing in the fact that we learn from various sources and we document our progress. We complete many tutorials, choose learning material. A thoughless copying without providing changes in it - and without learning at all - mostly doesn't happen.
If our code was based on somebody else's code, we should add such information .
Maybe we use an old tutorial - for example, we write an application with Rails 3 tutorial. From scratch, in accordance with Rails 5 version, using new framework mechanisms. Certainly, it's worth mentioning here.
When our code was only inspired by another solution/an application, you can mention it and write the way you got inspired, what changes you made, what functionalities were developed.
When we solve the sets of exercises, it's worth adding where others can find their description. If we will want to come back to these sources, the link will come up easily. This way, the author who shared his/her knowledge is, spent his/her time to prepare and share this material is also respected.
Information on the author, contact, www and social media links, a type of license under which the code is made available or the information on how to contribute to a project - these are only the examples of what can be added to your project.
A good, legible README
The suggestions above are mine. The most importaint point is just legibility. A thorough documentation make your repository shine in front of the recruiters and other programmers. There are many approaches to writing a good README. Take a look at the following examples:
- Node-chat – a simple description, screenshot of the application, examples of use
- WebApp – a splendid example of description provided for a landing page type of website and application using API. Description how it works, screenshots, technologies employed in this solution, additional information on functionalities that will be implemented
- Pomolectron – we have a logo, the screenshots, an instruction on installation and a description how it works
- Git point – exemplary Android application. A table of content makes navigation easier, the screenshots, mentioned functionalities, and information how to support application's development
README template
I leave you here an example of README.md file template you can download . Take a look at its formatting, and copy a raw version to your README.md file.
The article is also available in Polish on Flynerd.pl blog.
Instantly share code, notes, and snippets.
PurpleBooth / README-Template.md
Project title.
One Paragraph of project description goes here
Getting Started
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
Prerequisites
What things you need to install the software and how to install them
A step by step series of examples that tell you how to get a development env running
Say what the step will be
End with an example of getting some data out of the system or using it for a little demo
Running the tests
Explain how to run the automated tests for this system
Break down into end to end tests
Explain what these tests test and why
And coding style tests
Add additional notes about how to deploy this on a live system
- Dropwizard - The web framework used
- Maven - Dependency Management
- ROME - Used to generate RSS Feeds
Contributing
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
We use SemVer for versioning. For the versions available, see the tags on this repository .
- Billie Thompson - Initial work - PurpleBooth
See also the list of contributors who participated in this project.
This project is licensed under the MIT License - see the LICENSE.md file for details
Acknowledgments
- Hat tip to anyone whose code was used
- Inspiration
Karosuo commented Feb 26, 2021
Great format, thank you! :D
Sorry, something went wrong.
GruelingPine185 commented Mar 23, 2021
This was very nice... solid 20 second scroll to write this lol
Otromascomotu commented Apr 7, 2021
Hi Purp! Excellent contribution! I liked...
ardaorkin commented May 3, 2021
Awesome!!! Appreciate!
karma-systems commented Dec 12, 2021
Great, Many thanks.
sajith-rahim commented Jan 5, 2022
Thank You :)
yuis-ice commented Feb 2, 2022
One of the greatest readme doc. Thanks mate.
vonshirco commented Mar 2, 2022
Very useful, thanks🤝🏾
MekongDelta-mind commented Mar 3, 2022
There are many templates out there. I found your's the simplest. This is the most to the point template without any flashy badges.
IsaacNdala commented Mar 5, 2022
Great Job! Thank you so much!
Gizachew29 commented May 5, 2022
Great Readme, Thanks.
Soohan-Park commented May 30, 2022
choikangjae commented Jun 22, 2022
Outstanding Thanks! It didn't just give me how to write down the README but also give me enlightening what I even don't know about my projects need.
rodaw92 commented Jul 2, 2022
Amazing, Thank you
rami-HP commented Jul 6, 2022
Thank you 👍
ilovecopy commented Jul 18, 2022 • edited
If I have a screenshot or picture about my project,Which paragraph should I put the picture in the readme?
DaniCelis25 commented Jul 28, 2022
Thank you! About to use that template.
lucianoambrosini commented Aug 6, 2022
Great job! Thanks a lot!
NSGholap commented Sep 23, 2022
Thanks you search me a my way so very very Thanks
sdn0303 commented Oct 4, 2022
Great job! thank you so much 🙏
Cuisine-De-Lapin commented Nov 9, 2022
Thanks! Great job!
AbdoulkadriBoureima commented Jan 5, 2023
thisbilal commented Feb 1, 2023
Thanks a bunch ! This is exactly what i was looking for.
BubbaHexinator commented Feb 3, 2023
thank you great work
mfghelth commented Feb 17, 2023
Payment is not received please help me
Londino commented Feb 17, 2023
haram8009 commented Mar 4, 2023
thank you great work!
CodeNewbie Community 🌱
Posted on Mar 23, 2022
How to write a good README for your project
A good README.md is essential for any project. It is a summary of your project and gives users instructions & important information. This is a simple guide to help you make an accessible guide for your project.
What is a README?
A README is a file that explains the details and all important information for a project. A standard README file will have a .md (Markdown) extension and will be at the root of your project repo. Note: Get used to typing in the Markdown Language for your project README's! There is still a lot of different styling & editing options available in markdown vs .docx, .txt. etc.
The Structure of a README
Example of a good readme.
Project Title This is the must have of any project. It is important to know what your project is going to be about and the title represents that.
Project Description This is an important part of your project and what many developers and non-developers will look at. It is vital to have the most accurate and correct information. The description needs to be well written with no grammar errors and that is readable to users of multiple backgrounds. It is important to put some time and thought into writing the description of the project. It does not need to be long but needs to summarize the project. (What does your app do? What tech did you use?)
Table of Contents (Optional) A table of contents is good if you have a lengthy README and can help users navigate to sections quickly but is not a must have.
Getting Started This section typically is brief and will list the pre-requisites that the user must have in order to start using the project code. This section can be similar or be combined with the Installation section. (Ex: Must have node -v)
Installation This is where you will list the full instructions for users on how they can install and start using your project. This should include multiple steps and have detailed descriptions and outcomes for users. It is important to take your time and write these steps as thoroughly as possible. This will help users a lot and will help prevent users from coming back and asking follow-up questions.
Other Instructions, Specifications, Attributes, or Project Info This section(s) can include any other relevant project information. This can include information specific to a particular OS or Framework (Ex: Linux, React, etc) . Certain projects have specific instructions and information that may need to have their own separate sections. As you develop your project you will get a better idea of what you need to include in your README and how to structure it.
Contributing It is important to list all the names and information of the people who've contributed to the project. Be sure to include their GitHub Profile Name and any other social media they may want to have listed. There are some cool markdown contributing badges that I will list in the Good Resources below.
Acknowledgements Similar to Contributing it is important to include all the sources that helped you complete this project. It's always good to give credit where credit is due.
License Choose a license for your project. To learn more about license's check out choosealicense.com .
✧ Optional: Additional Sections
How to Contribute to the Project Add ways that that developers can contribute to the project. Tests Write tests for your application and then provide examples on how to run them. Examples You really go the extra mile when you provide examples of your code/application. This could be a screenshot, code block, video, webpage, etc. This can be really helpful to your users. Badges Try adding some cool markdown badges! There are badges at sites like shields.io and they include important code monitoring and other tracking info. Check out the Good Resources section below.
Good Resources
- Make a readme the basics of a readme.
- Awesome Open Source has some great README templates.
- CLI readme generator a command line package.json & git config file.
- Shields.io badges for all your markdown documents.
- Badges Generator create your own markdown badges.
- Contributing Badge a contributing badge for your project README.
- choosealicense.com information for license's for projects.
- Open Source License Article information on open source license's.
👋 Thanks so much for reading this article! Please check out my other articles on Dev.to and connect with me on LinkedIn .
Kendra Wing Follow
This article was originally published on Dev.to on March 23, 2022, by @kwing25 .
Top comments (3)
Templates let you quickly answer FAQs or store snippets for re-use.
- Email [email protected]
- Location Montreal, Quebec, Canada
- Work Netlify
- Joined Jan 12, 2021
Great stuff! Thanks for sharing. There’s also readme.so from Katherine Peterson for folks looking for readme templates.
GitHub @github Try out this handy tool from @katherinecodes to help create and customize your next project's README 📖 readme.so 11:00 AM - 23 Apr 2021
Looking forward to your next post!
- Joined Jul 21, 2022
This is a great example of what a README should look like. It provides a quick overview of the features and how to get started writing .
A great README is worth a thousand lines of code! It is the first thing visitors see about your project and can determine whether or not the viewer will give your project a chance.
Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink .
Hide child comments as well
For further actions, you may consider blocking this person and/or reporting abuse
Want to Learn Java Quickly? Burn All Your Java Tutorial Books
John Selawsky - Jan 15 '21
Cookies vs Local Storage
Pragati Verma - Jan 15 '21
Let’s Develop an E-Commerce Application From Scratch Using Java
Nil Madhab - Jan 15 '21
Python Web-Scraping Basics: How to go to a Website, Fill Out Forms, Click Buttons, and Scrape Data.
Ethan Schreur - Jan 15 '21
Once suspended, kwing25 will not be able to comment or publish posts until their suspension is removed.
Once unsuspended, kwing25 will be able to comment and publish posts again.
Once unpublished, all posts by kwing25 will become hidden and only accessible to themselves.
If kwing25 is not suspended, they can still re-publish their posts from their dashboard.
Once unpublished, this post will become invisible to the public and only accessible to Kendra Wing.
They can still re-publish the post if they are not suspended.
Thanks for keeping CodeNewbie Community 🌱 safe. Here is what you can do to flag kwing25:
kwing25 consistently posts content that violates CodeNewbie Community 🌱's code of conduct because it is harassing, offensive or spammy.
Unflagging kwing25 will restore default visibility to their posts.
- Writing good README files
- Edit on GitHub
Writing good README files
What should be included as a bare minimum in README files?
Write a README file according to good practices.
The README file (often README.md or README.rst ) is usually the first thing users/collaborators see when visiting your GitHub repository. Use it to communicate important information about your project! For many smaller or mid-size projects, this is enough documentation. It’s not that hard to make a basic one, and it’s easy to expand as needed.
Exercises
This lesson is exercise-based with some hints at the bottom.
Instructor note
Groups can choose to work on either exercise README-1, or on exercises README-2 + README-3.
Exercise README-1 creates and discusses a README for an example Python project.
Exercise README-2 can be interesting if learners already have a project/code of their own.
Exercise README-3 (constructively) discusses READMEs of projects which you have recently used.
Exercise: Basic readme
Exercise README-1: Write a README file for an example Python project
The example project
Here’s the example project . For this project we transformed the code snippets from the previous episode into a single script analyse_spreadsheet.py
Let’s take a look at the script . You don’t need to understand the script completely, all you need to know is:
The functions mean_temperature and get_spreadsheet_columns from previous episode are in there.
We added a main function that is called when you run the script (you could run this python script by calling python analyse_spreadsheet.py on the command line). It will prompt the user for a file name, print the columns in the spreadsheet, and print the mean temperature.
That’s all there is to this project! (You can ignore the other files in the repository, we’ll get back to them in episode 4)
The exercise
Fork the the example project to your own github namespace
Add a file called README.md (you can use the github web interface or work locally (i.e. git clone , edit the file, git add , git commit , git push ))
Add some content to your README file. Think about what you want the audience to know about your project! It does not matter whether the information is correct, it is more important that you have all the components that make up a good README file.
Note that the README file is nicely rendered on the github repository page.
Compare your README file with that of others, is all the essential information in there? NB: The README.md file is written in ‘Markdown’ a very popular lightweight markup language, all you need to know for now is this syntax:
(Optional): Use https://hemingwayapp.com/ to analyse your README file and make your writing bold and clear!
A README file for this project could look like this:
Exercise: Readme of your own project
Exercise README-2: Draft or review a README for one of your recent projects
Try to draft a brief README or review a README which you have written for one of your projects.
You can do that either by screensharing and discussing or working individually.
Please note observations and recommendations in the collaborative notes.
Exercise: Readme of another project
Exercise README-3: Review and discuss a README of a project that you have used
In this exercise we will review and discuss a README of a project which you have used. You can also review a library which is popular in your domain of research and discuss their README.
When discussing other people’s projects please remember to be respectful and constructive. The goal of this exercise is not to criticize other projects but to learn from other projects and to collect the aspects that you enjoyed finding in a README and to also collect aspects which you have searched for but which are sometimes missing.
Table of contents in README files
GitHub generates a TOC for README.md .
On GitLab you can generate a TOC in Markdown with [[_TOC_]] .
With RST you can generate a table of contents (TOC) automatically by adding .. contents:: Table of Contents .
What makes up a good README file?
As a bare minimum a README file should include:
A descriptive project title
Motivation (why the project exists) and basics
Installation / How to setup
Copy-pastable quick start code example
Usage reference (if not elsewhere)
Recommended citation if someone uses it
Other related tools (“see also”)
User experience
Think about the user ( which can be a future you ) of your project, what does this user need to know to use or contribute to the project? And how do you make your project attractive to use or contribute to?
IMAGES
VIDEO
COMMENTS
How to Write a Good README – a Step by Step Guide · What was your motivation? · Why did you build this project? · What problem does it solve? · What
Learn how to make a great README for your programming project, ... While READMEs can be written in any text file format, the most common one that is used
README format and writing style · Use short paragraphs. · Use bulleted or numbered list instead of comma separated lists. · Never ever use click
A nice README is a good way to help people engage in the project as well. A project with nice README and screenshots will get the attention of
Writing a good README - newbies manual ... Open a README.md. file in a new project. Make sure the file always includes the following elements:.
A template to make good README.md. GitHub Gist: instantly share ... README-Template.md ... This was very nice... solid 20 second scroll to write this lol.
Contribute to matiassingers/awesome-readme development by creating an account on GitHub. ... "How To Write A Great README" - Caleb Thompson (thoughtbot)
The Structure of a README · Project Title This is the must have of any project. · Project Description · Table of Contents (Optional) · Getting
A brief history of bad READMEs Before we dive into why you want a good README and how to make one, let's take a look at some of the most
What makes up a good README file? ... As a bare minimum a README file should include: ... Think about the user (which can be a future you) of your project, what