Hacker News new | past | comments | ask | show | jobs | submit login

I myself appreciate READMEs that tell simply what the project does with a couple of good examples and links to the full API description. I dislike pompous and overly embellished APIs as it makes it seem that the author(s) care more about looks than the content, so I wouldn't go overboard with images and badges and whatnot.

The fact is you can't satisfy all users or all use cases so making me, the developer, not waste any of my time trying to implement something that is not possible with the library makes me really appreciate it even though I may not end up using it.

Being boring isn't necessarily bad. It's just that under- or over-communicating is a delicate balance that has to adjusted based on the project and its scope.




About badges: Though I certainly don't advise anyone adding twenty silly badges to their README, seeing a pipeline status, code coverage (and depending on the language, the code style) makes me assume that the project cares about quality and have the know-how to ensure that the quality is measured.

If the project maintainers added a GitHub stars counter, then I assume they check their starts, and I'll consider staring their project (one sec and could make the maintainers 0.1% happier). In case I see a Twitter badge, then I'd follow them.

So I see the first group as a signal about what I need to know before I pull in a dependency, and the second group as something I can do to make the maintainers day.




Consider applying for YC's Spring batch! Applications are open till Feb 11.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: