DEV Community

🚀 5 PRO Tips for an Unbeatable GitHub README! 🥊

Bap on November 30, 2023

Hi friends 👋 Today, let's look at how to write a KILLER GitHub README file. The README is the first touch point with anyone new to your repo. ...

Read full post

Dave Parr • Nov 30 '23

Very much agree.

My partcular current favourite is:

Write an introduction
A summary explaining the purpose and target audience of your project.

I've been handling readmes en masse for my current pet project

DaveParr / starpilot

Use your GitHub stars for great good!

Starpilot is like copilot, but for GitHub stars.

I've been starring repos for years thinking "This will definitely be useful later".

However I never really went back to them.

Starpilot is a retrival augmented generation CLI tool for rediscovering your GitHub stars.

Starpilot helps this problem by allowing you to rediscover GitHub repos you had previously starred that are relevant to your current project.

Here's some more details about the motivation for and state of the project.

Installation

This project is in early development and is not yet available on PyPi

Fork repo
Clone repo
cd starpilot
poetry install

You will also need to have downloaded models/mistral-7b-openorca.Q4_0.gguf from GPT4All, or an alternative supported by the Model class and included it in the models directory.

You will also potentially need Pandoc installed on your computer if your starred repos contain a rst formatted Readme that you want to load…

View on GitHub

I've noticed 2 things about README.* which has been particuarly irritating for the project:

Many repos approach the read me as 'the document that tells a developer how to set up a development environment', and I agree that is a big part of the document, but definately not it's only part.
GitHub supports a few 'exotic' standards for readmes, including Python RST. FWIW it's worth I'm relatively pro that generally, but support for these less standard standards does mean for projects like StarPilot that handle README documents as part of the core software, it does add some interesting complexity, and I'm sure for a few people will be the edge cases that throw errors in using star pilot currently.

Bap • Nov 30 '23

Mhmm super interesting insight. True, many developers look at it too much as "how to set things up". The point number 2 is one I was not aware of these "exotic" standards lol - thanks so much for sharing it here 🙏

Nathan Tarbert • Nov 30 '23

Good stuff!
I'd also add that you can add responsive images based on user preference in MD as well.

Bap • Nov 30 '23

Pretty cool 👀
Thanks for sharing!

Nathan Tarbert • Nov 30 '23

You're welcome!

flo merian • Dec 6 '23

great read, @fernandezbaptiste!

FWIW I recently stumbled upon Repobeat by Axiom, an elegant dashboard that shows your open-source project’s health.

if you value open metrics and transparency, you HAVE to add it to your README file.

Bap • Dec 6 '23

That looks really cool flo! Thanks for sharing that with me :)

Hossein Yazdi • Dec 5 '23 • Edited

Thanks for sharing. Great tips. Now, as an add-on, this tool here makes creating README files super simple. Hope devs here find it useful!

Bap • Dec 5 '23

Ouhhh always love checking these out, thanks a lot Hossein! 🦾

Hossein Yazdi • Dec 5 '23

You're welcome Bap! Happy to have shared it! 😊

Matija Sosic • Dec 5 '23

Nice and comprehensive guide! Do you have some favorite Readmes you can share?

Bap • Dec 5 '23

Thanks for this! I don't think I have a favourite per se but I do think the ones from Novu (github.com/novuhq/novu) or Hoppscotch (github.com/hoppscotch/hoppscotch) are really nice.