Data-scientist who loves to use #datascienceforgood, especially in ecology, energy and the environment. Bonsai, gardening, bikes and music when I'm not at a keyboard.
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.
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 🙏
Very much agree.
My partcular current favourite is:
I've been handling readmes en masse for my current pet project
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
cd starpilotpoetry installYou will also need to have downloaded
models/mistral-7b-openorca.Q4_0.gguffrom GPT4All, or an alternative supported by theModelclass and included it in themodelsdirectory.You will also potentially need Pandoc installed on your computer if your starred repos contain a
rstformatted Readme that you want to load…I've noticed 2 things about
README.*which has been particuarly irritating for the project: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 🙏
Good stuff!
I'd also add that you can add responsive images based on user preference in MD as well.
Pretty cool 👀
Thanks for sharing!
You're welcome!
Ouhhh always love checking these out, thanks a lot Hossein! 🦾
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.
That looks really cool flo! Thanks for sharing that with me :)
Great article! If anyone is into creating more custom badges can check out my article about that; dev.to/mlkrsrc/how-to-make-custom-...
Thanks Mustafa, I just liked your article 🙂
Nice tips!! Thanks for this
You are very welcome! Glad you enjoyed it :)
Yes, my readme after this post:
LOL
Cool summary thanks, great ideas for us to improve our README!
Thanks for the kind comment! Glad it helped 🤓
Nice and comprehensive guide! Do you have some favorite Readmes you can share?
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.
Great tips for improving READMEs :)
Thanks a lot Nevo - always means a lot coming from you 💛
Great tips ! Tried to apply them on my open-source project metric observability project 🤗
I really like it, looks super neat 👌
Happy it helped!
Ah yes, shields.io for the badges! :D