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 😡😡😡.
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:
- 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 🤘