Once you've started learning to code, one of the things you'd so often encounter is a README file while reviewing, learning from or contributing to open source software. I'm pretty sure you've heard the saying "Always have a README.md file at the root of your project" more often than not and my guess is that your reaction was similar to mine - "What exactly is that?". In this article I carefully explain what a README.md file is, its basic structure and what it should contain.
Firstly, what is a README.md file? It's simple - It is a file that contains all the necessary and important information of your project. This is where you document important information about your project think of it like a project summary or a manual for your project where anyone can have access to be able to have an nderstanding of what your project is, how to use or implement your project source files. Its importance cannot be overemphasized, it is best practice to always include one at the root of your project as well as carefully go through the README file of any open source project(s) you intend to interact with. Notice that this README file always has a '.md' extension and this indicates it is a Markdown file type and therefore it should be written with the Markdown syntax. Please see my article to learn and get started on basic Markdown syntax here.
A README file should contain:
- The file name as the header
- An introductory paragraph
- Table of contents
- Project overview
- Project process
- Author
The header is usually the project name as a title of the README file, then following that is a descriptive paragraph on what the project is about. The table of contents contain subheadings to further describe the project in details. The first subheading is the overview, this section contains detailed explanation of the significance of the project, link(s) to where your project is histed if its live and may contain snippets/snapshots of the project as well. The second subheading details the project process. Here, the technologies used in development, some tips or particular skills you picked up working on the project and some helpful resources should be highlighted. Finally, you can attach some personal external links to the author section for ease of contact to people who want to reach out to you for collaboration, learning or opportunity sake. Note that each subheading can further be split into smaller sections (sub-headings) for better structure. There you have it! I hope this helps.
Top comments (0)