I’ve spent a lot of time working on my most recent project. Continuously looking for ways to refactor, improve and elevate the level of my code and in turn, the application itself. Only to realize that I have not constructed a README file before I deploy. I’m sure that I am not the first developer to encounter this situation, and I’m certain that I will not be the last. This has inspired me to share with you how to create a README file, using the common ‘Markdown’ syntax.

What, why, when, where and how?

What: A text file that introduces anyone viewing your project to it, and also explains what the project is.

Markdown output
Preview to be rendered

Structure and suggestions for your README file

The first thing to include, and maybe the most obvious is the name of your application. The Markdown Reference section on CommonMark provides the syntax needed for some light formatting. Such as, headers, italics, links, images, etc.

Created using Shield.io

Make the most of your time!

Remember, you are putting your time and energy into your application. Possibly collaborating with others. All of that energy could go to waste without a simple text file (README) in your project directory. If your audience does not understand what your application is, how to install and use it — what is the point of spending all the time in building the program.

Software Engineer | Full Stack Developer | Soccer Fanatic

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store