The benefits of writing a good challenge README

You may not have considered writing a README for your Frontend Mentor solutions. While it is tempting to move on to the next challenge and start a new project, skipping over the README might result in missing out on some incredible benefits.

I have completed over 30 Frontend Mentor challenges and written README files for all my challenge repositories. In this article, I will explain the value of writing a comprehensive README, not just for yourself but for the wider developer community.

What is a README file?

A README file is a file that gives people some information about a project. You often find it on a remote repository to inform people about the project. It is shown by default by all hosting services for projects using Git, such as GitHub.

Here is an example of a README from one of Frontend Mentor’s challenge starter downloads:

How does it work?

A README file is written in Markdown. Markdown uses a special syntax so that it can be rendered as HTML. This allows the author to format the document to make it easier to read. They can also include other elements like images and tables.

You can see the common Markdown syntax on the Commonmark. They also have a helpful 10-minute markdown tutorial.

Some Git hosting providers have more options. For example, GitHub allows you to use the HTML picture element to have different images for light and dark modes. That is only available on GitHub. You can see all the syntax for GitHub Markdown on the documentation.

If you use a different Git hosting provider, I recommend searching for its Markdown syntax documentation.

You already have a README.md and README-template.md in Frontend Mentor’s challenge starter files. The README-template.md is a guide that you can use to write your README once you have completed your project. I recommend following the guide. If you want to start simple, write what you have learned after finishing a challenge.

What do you get from writing a README?

I have experienced seven benefits while writing comprehensive README files. Here they are:

Get better at writing in English

You can write your README in your language, but the majority of people in the Frontend Mentor community understand English, so I highly recommend writing it in English. English is not my first language, so writing in English has been an enormous help.

You encourage yourself to learn English if you write your README in English. You can start by using a translator to translate a word or phrase from your language to English. In this way, you can learn English bit by bit by writing your README.

I recommend using the following tools to help you write in English:

• Google Translate
• Grammarly
• Dictionary.com

Practice explaining what you mean clearly

Your first draft is not the final document. You need to read and rewrite what you have written before. Your writing will help you understand a new concept you have learned. If you read what you have written and do not understand it, chances are you do not fully understand what you have learned.

The process of creating a README is the same as writing code. You need to do some refactoring to get good results, but the satisfaction of making improvements always feels good.

I recommend using Hemingway to help you improve your writing. It enables you to identify the following things:

• Long sentences

• Passive sentences

• Complex words

• Adverbs

Become a reference for yourself and others

If you can write clearly about a new concept you have learned, you can use your README as your reference in the future. This can save you time. You do not need to browse the internet and reread articles because you have done that already. You can read what you have written before and get your answer. Your future self will be happy.

Your README can be a reminder for yourself. You may forget how you did something in the future, but you do not need to worry because you have written about it already.

Remember, you are the best person to understand your writing. That is why writing what you have learned will always benefit you.

Not only that, your README can also help someone else who is struggling with the same issue. You can help others to understand the problem and the solution. They can read an explanation instead of code. They can learn the "why" and the "how" through your README.

By helping others to solve their problems, you open up opportunities for others to connect with you. What is a better way to connect with someone than by helping them?

Remove the need to explain your approach

Your solution may contain a tricky decision. You may choose to create a layout using CSS Flexbox rather than CSS Grid. Your README can be a place to write your reasons for deciding on this approach.

Mentors who are reviewing your code can read your README. Your README allows them to know your level of understanding. If they have a better solution, they can provide it while learning the reasons for your solution. This can lead to a discussion that can help you see a different approach. As a result, your README can lead to high-quality feedback.

Now, if the mentor does not know why you chose a specific approach, they may be unable to provide helpful feedback. They may ask, "Why did you do it like this?” You can skip this step and get more useful feedback on your specific approach by providing your reasoning in your README.

This not only saves you time but also the time of those who are trying to help you.

Help you write a good resume

If you want to apply for a job, you must write a resume. Your README can act as a guide.

Your READMEs can help you write your skill section in your resume faster. You can use your READMEs to summarize your skills for each project into bullet points for your skill section. This can save you a ton of time when figuring out your skills.

Your READMEs help you identify your skills confidently. For example, you can be confident writing, "Made five projects with a deep understanding of accessibility in mind." You can be confident when writing that point because your project demonstrates this skill, with its own README outlining your approach.

Act as motivation for yourself

When you feel down or need motivation, you can read your READMEs.

Your README is proof of your hard work. You want to take some time to write down what you have learned. Your README is proof of the effort you put into your project and the progress you have made.

Have you ever played a video game? Do you feel great every time you see good progress? Your README can be a tracker of your skill. For example, the README of your first project shows that you only understand a bit about CSS Flexbox. On your second, you start using CSS Flexbox with a better technique. You know that you are getting better.

Improve your code

You can also see your improvements after you finish each project. When you write your reasons for your approach, you may find a better way of doing something. You can improve your projects. Then, you can write why your new approach is better than the old one. You can feel satisfied when you know that you are making improvements.

Conclusion

Here are seven key benefits of writing a good challenge README:

• You will get better at writing English.

• You will learn how to write clearly.

• You have your personal reference that can help yourself and others.

• You remove the need to explain your approach to solving a problem.

• You have a guide to help you write your resume.

• You have your personal source of motivation.

• You can improve your code.

I encourage you to start writing a README whenever you finish a challenge. I highly recommend writing at least what you have learned. That way, you can get all the key benefits. If you need some inspiration, please feel free to check out my GitHub repositories. Here is a link to one of my challenge READMEs showing what I write about.

Write code, write a README. Happy coding, happy writing.