Table of contents
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. One of the major challenges junior web developers pass through is having to include vital information on their projects in markdown files. When I first started as a developer, it took quite a while for me to understand the flavors of markdown files and how to make my work look professional and not shabby.
In this post, I want to share a few vital things you should know to understand how MD files work. These will help you get over the resistance that all new developers face and hopefully give you the confidence to give professional info about your projects and technical documentation.
What is Markdown?
Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages.
Using Markdown is different than using a WYSIWYG editor. In an application like Microsoft Word, you click buttons to format words and phrases, and the changes are visible immediately. Markdown isn’t like that. When you create a Markdown-formatted file, you add Markdown syntax to the text to indicate which words and phrases should look different. The markdown can be used for everything. People use it to create websites, documents, notes, books, presentations, email messages, and technical documentation.
How Does it Work?
According to markdownguide.org, there are four steps to this:
Create a Markdown file using a text editor or a dedicated Markdown application. The file should have a .md or .markdown extension.
Open the Markdown file in a Markdown application.
Use the Markdown application to convert the Markdown file to an HTML document.
View the HTML file in a web browser or use the Markdown application to convert it to another file format, like PDF.
For web developers, however, those who use editors like visual studio code, sublime text, and the rest only have to create the file with a md extension and preview as it's being updated.
Is there a standard README format?
Well, there is none so it's really up to the developers to decide what information would be included in the README file.
However, below is a list of what I feel your readme file should contain:
** Name**: this entails a self-explaining name for your project.
Description/ Overview: This contains brief information about what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. If there are alternatives or possible contributions to your project, this is a good place to list differentiating factors.
** Badges**: 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.
** Visuals**: depending on what you are building, it can be a good idea to include screenshots of your project.
Installation: it is necessary to include details of the languages and libraries used while building the project. You need to 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 use your project as quickly as possible.
Roadmap: If you have ideas for releases in the future, it is a good idea to list them in the README.
Useful Resources: it is essential to refer to materials, videos and other resources that were helpful while building the project. You can also add links to the materials or websites.
Authors and acknowledgment: it is also important to show your appreciation to those who have contributed to the project.
License: for open-source projects, you need to say how it is licensed.
My next write up for this series will shed more light on how to add these contents and the proper indentations to be used in your readme files.
***I hope this was helpful?? ***