In this tutorial, you will learn how to create beautiful and consistent 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 is the first documentation most developers will see when they clone the project. This is why the humble is the king of coding documentation 👑👑👑.

Writing a good is important and a lot of developers assume it is easy, however, I have seen lots of badly written files in my time. Different developers can have different opinions on how a 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 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 files in your company are written in a consistent manner? This is where readme. so can help 🔥🔥🔥

What Is a

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 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 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 instead of trying to remember what to include, it's easier to use a template. is an online templating system. It will dynamically create a 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 generated file will look like:

How To Create Beautiful Developer files easily - 1

Bookmarking and using will prevent you from remembering all the information in this tutorial. Next time you want to create a, simply fire it up, decide what you want to create, click the Generate button and you will have a skeleton template that you can copy and paste within your project. If everyone in your company uses you can also ensure that all your files are structured the same way 💥 💥

How To Create Beautiful Developer files easily - 2

Even though comes with a lot, my personal recommednation on creatin a bitchin, is to focus on dexriving what the proejct does. Every 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 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 files. Its not hard to create beautiful files. If youa re not using Readme.So yet, I suggest you check it out. Happy Coding 🤘