A README is one of the most important files of any programming project. It's a text file that introduces the project and explains what it's about. It helps people understand how to install and use the code you've written, as well as how people can collaborate with you.
Why Write a README?
Back in 2010, Tom Preston-Werner argued in favor of README driven development (RDD). Write your README first, before you do anything else. He said that, while particular programming methodologies and ways of working like TDD and SCRUM are great, none of it matters if people don't know how to use your code.
Writing a Readme is absolutely essential to writing good software. Until you’ve written about your software, you have no idea what you’ll be coding.
A README finds that rare middle ground between coming up with specs while you're programming versus adopting a slow and inflexible waterfall model with reams of specs.
On top of that, as Preston-Werner says, it's much easier to write a great README at the start of your project, when you're at your most motivated. When you're at the end of your project, writing a README will feel like another task, another chore.
But you need a great README, because very few people will plunge into your code to understand how it works. It's time-consuming and they might not have the technical expertise to understand it.
In addition, it's not just developers who look for your README. Recruiters, too, look for READMEs to understand what you're capable of. While a good GitHub profile will definitely help, your individual projects need READMEs as well.
Even if you're writing code just for yourself, a README is important. Consider your future you, who might return to projects you've written years ago. With a good README, you'll immediately understand what that project was about and how it can still be useful to you today.
What to Include in Your README
Here are some of the essential things to include when you're writing your README. We'll assume that you're familiar with markdown to organize your file and make it look good.
- Title (can be text or an image)
- Introduction (what it's about & why you wrote it)
- How to install
- How to use
- Technologies used (libraries & versions, helps recruiters)
- Acknowledgments
Those are the absolute essentials. They make for a good README. If you want to write a great one, you can take it a step further and include:
- Table of contents (useful if your README is long)
- List of features
- Examples of use (with code or images)
Great README Examples
- ai/size-limit: great images and comprehensive explanations.
- crelies/AdvancedList: concisely explained and great use of emojis.
- maxvoltar/photo-stream: nice ToC, good install section, credits.
- release-it/release-it: has a GIF, comprehensive instructions.
- ArmynC/ArminC-AutoExec: clean features table, clear description.
A README is an essential file for your programming projects, even if it's just for yourself. What do you think? Is there anything else you think is essential to a README? Let me know in the comments 👇
Top comments (0)