In this tutorial, you will learn how to create beautiful and consistent readme.md files easily using a new tool called Readme.So. In my role as head of development, I have to juggle lots of projects at the same time. Having reliable documentation is a key aspect for getting up to speed on a project. I have wasted weeks of my life trying to set up a new project due to a lack of set-up instructions. Good documentation can prevent this rage from occurring 😡😡😡.
The readme.md is the first documentation most developers will see when they clone the project. This is why the humble readme.md is the king of coding documentation 👑👑👑.
Writing a good readme.md is important and a lot of developers assume it is easy, however, I have seen lots of badly written readme.md files in my time. Different developers can have different opinions on how a readme.md file should be structured. If you work in a company like mine, where I have lots of teams, working on lots of projects, it is very common for the readme.md files to be structured very differently. This can increase the burden of a developer getting up to speed on all of our companies projects. How do you make sure that all readme.md files in your company are written in a consistent manner? This is where readme. so can help 🔥🔥🔥
What Is a README.md?
The origin of the README file is not 100% clear. Some claim it originated from Programmed Data Processor in 1974, however, other geeky types dispute this 🤼♂️🥊🤼♂️. The README.md file should be stored in the root of a project. When someone views the project in a tool like GitHub, it will display on the homepage. A great project readme.md should explain what the project is about, how to install it, the coding standards followed on the project, how to run the tests and any dependencies or notes the reader should be aware of.
When creating a new README.md instead of trying to remember what to include, it's easier to use a template. readme.so is an online README.md templating system. It will dynamically create a README.md file and present you with a load of options. You can choose to include 28 different sections. Sections range from acknowledgements, contributing, demo info, deployment documentation, installation, lessons, license and tests usage. Here is an example of how a readme.so generated readme.md file will look like:
Bookmarking and using readme.so will prevent you from remembering all the information in this tutorial. Next time you want to create a README.md, simply fire it up, decide what you want to create, click the Generate button and you will have a skeleton README.md template that you can copy and paste within your project. If everyone in your company uses readme.so you can also ensure that all your README.md files are structured the same way 💥 💥
Even though readme.so comes with a lot, my personal recommednation on creatin a bitchin readme.md, is to focus on dexriving what the proejct does. Every readme.md should include:
- Title
- Description of what the project does
- Technologies used
- Painful bits - document any hidden gotchas and problems someone new to the project mioght encounter
- Installation setup
- How to run the tests
- Badgets (the build status)
For insipration, an example of how I structure my personal projects readme.md file can be found here. As you will see I include descriptions, how to clone, demo URLs, and set-up instructions.
Content Is King
Obviously, just having the right sections is not enough, content is king afterall . Below outlines some tips that I have found useful on my projects:
- Try not to be preachy
- Code snipepts and terminal commands are very useful
- Wrtite using a human friendly tone
- Good writiung should be short, sharp and should not contain unneeded word
- Use standard sections and heading
- Use a markdown linter (like markdownlint
- Avoid acronyms and idioms
- Ensure all chages are code reviewed like any other code file
- The most important one... DON'T BE A DICK 🥴🥴🥴.
That is pretty much all you will every need to know in order to create beautiful README.md files. Its not hard to create beautiful ReadMe.md files. If youa re not using Readme.So yet, I suggest you check it out. Happy Coding 🤘
