Building software is fresh, but without effective sharing of it, it loses its touch. Sharing of it-in the sense that communicating it effectively well enough to be understood and hacked. Software that can not be hacked is just software that is not understood, beyond a threshold of detail that is.

Now for this article my approach is explaining by example, not by detail, as this is to be an experiment in effectively communicating the most important pieces: How to make a great readMe to tell as much useful information as possible with respective contexts.

Pre-requisites:

• Readme’s are Markdown files that explain how an associated repository operates
• Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents
• You, the software architect, is in charge of deciding what is important to be communicated to the potential user or customer

Fun fact: this shit website doesn’t allow markdown so we’ll just use screenshots with links

I will explain using different repositories I have such as
https://github.com/jongan69/ExpoRouterAuthTemplate

It is a Mobile and SWA Expo React Native application

• Its a website and mobile app in one
• It has authentication signin/signout functionality for both web and mobile

Let go over where we started

We used chat for the template for speed and then got started making changes, we are aiming to make our readme as useful as possible without overload.

We got 5 sections:

• Getting Started -> How to setup and run
• Deployment -> How to deploy
• Features
• Contributing
• License

First -> sharing the product

• Action buttons

Used Vercel Github action for builds that allowed for automatic url adds on push, can also be done with GitHub pages

Since Markdown can render images so why not use that to the fullest?

for example: my GitHub page

There are many api products that take in data via a get requests and return images with the respective data

If you click the drop downs in the readme you can see what I mean

There are many free tools for dynamic and static badges:

badge-generator

Jacoco-badge-generator

GitHub - cicirello/jacoco-badge-generator: Coverage badges, and pull request coverage checks, from JaCoCo reports in GitHub Actions

By writing beautiful readMe’s, you create software that users and developers can appreciate more.

bc1qncghs2skza0l2fgfg42sxm0hweejhafupczegs