alt Hacker NewsCan I please congratulate you on your README. It rapidly tells me what I'm looking at, and why I might be interested in the project. There are so many READMEs around that ... just don't do that. They ramble about technical implementation details, how their language choice is amazing, and a third of the way through the README, I'm still left wondering, "but what does this project do?".
Replies
Many of my old >1K star GitHub projects were not that great, but I always made sure to create the cleanest, simplest possible READMEs, inspired by things like the Python requests library's docs (https://github.com/psf/requests). I think it helped a lot in their success.
I remember someone once created a GitHub issue requesting I turn the README into some verbose technical thing with full API docs and a bunch of people replied saying they greatly preferred the "pitch + high-level examples" style.
Yes, this is definitely one of my pet peeves. Just give me input --> output, then everything in between.
Yes, this is so important and yet so often not considered. This README was pretty good, thorough and not ambiguous. The number of projects that assume you know what their obscure idea relates to is huge, mainly as the authors can't put themselves in the shoes of their audience.
It still sounds like LLM which is nauseating to read. For instance: "Blender's interface is famous for how it feels. You press a number field and drag: the cursor vanishes, the value glides under your hand, and you never hit the edge of the screen. " that's ChatGPT writing.
Not to mention that it includes screengrabs! Which a shocking amount of gui and web projects dont do
I'm confused. Are you being sarcastic? Isn't this readme in the most typical LLM-ism?
I find it to be confusing LLM spam. It spends a lot of time talking about Qt APIs, and dearimgui... most of which could go in a separate page.
But the worst part is all code snippets are followed by an image which is not related to the code snippet. It's not what you get by typing the code... it's something completely different.