Relatable Code

Introduction

It’s been a while since I added an entry to the series, for the past few months it’s mostly just been working through submitted bugs and added small features! But after some conversations, I figured I’d add another entry explaining the thought process for working through the README file.

A good readme can give a base explanation of the intention and proposed solution of the project as well as give a quick guide on how to start contributing to the application (if it’s open-source)

Here’s the README to check it out while reading through this short blog post.

Status checks

At the very top of my README, I opted into leaving some quick status badges for several of the third-party libraries I have associated with my app: codecov, cypress, codeql, netlify, and several Github status points!

I feel like this gives a pretty sweet overview of the health of the app!

About

I split this section up into two sections. A quick list of the main features of the app and a ‘How it works’ section with gifs and screenshots! I feel like these screenshots give a much more tangible view of how the application works. These can be hooked up pretty easily using Imgur and giphy.

I upload the necessary gifs and images and simply link them through the markdown:

Markdown
<!-- Example Gif -->

![til](https://cdn.hashnode.com/res/hashnode/image/upload/v1641742153586/vqNTttGTF.gif)

<!-- Example Image -->

![Imgur Image](https://cdn.hashnode.com/res/hashnode/image/upload/v1641742155213/ksJzopDyo.png)

Quickstarts

Afterward, I include several sections that help other contributors get quickly started with the app with the following sections:

• Prerequisites —I quickly lay out the CLI commands to get started
• Running the tests — Commands needed to double-check over the code and make sure everything is still A-okay
• Roadmap — Just a small section linking to the issues page for the Github repository to know which issues can be worked on
• Deployment — Brief summary on how the project is deployed to netlify
• Versioning — Explanation of how versioning works. In this case, SemVer is used as it seems to be the industry standard

Contributing

This is probably one of the more important sections of the entire README where you can reference, at least in my case, a CONTRIBUTING.md for a more in-depth explanation of how to contribute to the project.

Github can help out with a generic format but I suggest making adjustments respective to your project.

Ideally, this section should reference the CODE_OF_CONDUCT and any special steps needed for the pull request process.

Miscellaneous

At the very end, I added a small section to be able to contact me as well as some legal information as the app is pokemon related in nature.

If you see any typos or errors you can edit the article directly on GitHub