What is a README? A README is a series of instructions, information, and/or guide which usually highlight a portion if not what an entire codebase does. A README is written in Markdown syntax which may be different then what you are accustomed to besides HTML syntax.
So why use a README? Well, the reason I started diving into writing READMEs and taking the time to fine tune them is simply because it makes my code accessible. It creates a guide by which those unfamiliar with my code or tech stack can gain a quick insight into the workings of my file structure, database management/schema, etc.
Now, how do you write a good README?
Title, short description, and image
Well first you need a title and I would recommend titling your README based on it's coverage. A README that you find as soon as you open up a repository should be titled the name of the repository or product. I would recommend h1 tags for this purpose. It also makes sense to put a short description (one sentence) of the overall purpose of the product or code here. I also recommend a picture directly under your README that is a representation of your code/product. This could also be a logo for your product! Maybe a picture of a key feature or a gif of your product in action. Images are written in markdown syntax with the img tag. An important note is that markdown syntax uses inline styling to position things, color things, size things, etc. So for an image I typically mark its source (src) maybe its linked in the files or hyperlinked where it is stored.
See an example below for one of my first title, description, and image.
Table of Contents
So you have a fancy title, a short description, and an image that gives some insight into your project/product. I believe the next thing that sets apart other READMEs is a table of contents. How do you create a table of contents with Markdown? Title the Table of contents with an h2 tag then use the following format.
Asterisk followed by closed square brackets that wrap the title of the content followed by parenthesis that enclose the link to the part of the README where the content is located.
Example:
Sections
After the table of contents, the contents naturally follow. What the contents are depends on your project/product but things that make contents easy to read are picture examples and code snippets!
How do you write a code snippet and what is it? Let's take a look!
Three tick marks followed by the language and inside the tick marks you can place your code block. After that close with three more tick marks!
function addTwo(num){
return num + 2;
}
So these are what I would consider the basics of a README. I want to expand on this later. I will also say that it has benefited me to look at professional products and study their READMEs. I hope this has been helpful to you! See you in the next post.
Top comments (2)
Nice article! I just wanted to point out that the "help" tag is for asking for help, not for sharing helpful content.
I usually use readme.so, it's a simple readme generator that is highly customizable.