How to make a good-looking README for a GitHub repo?

yegor256.com

15 points·yegor256a··5 comments

The advice about badges reads like parody to me. I only really care if the project has CI. The Zoid repo has way too many!

I focus on making sure the mobile view of the github page has a compelling summary of the state of the project “above the fold”:

- purpose and goal

- programming language

- software type: library, framework, language, CLI, server, etc

- maturity: age, production-readiness, prominent users, corporate backing

Logo is a nice-to-have.

I agree that I don't understand the author's take on badges, particularly because they even admit:

> They don’t really deliver any valuable information.

I've yet to ever see a badge on a GitHub repository that offered useful information I couldn't find in a more convenient place. The Zoid repo is particularly a case where it just feels like the love of badges in README's is some leftover from the 1990s web design world where every web developer seemed to love all their "Works in IE", "Best in Netscape Navigator", "Made in Dreamweaver", "HTML 3 Compliant", "Grandmother Approved", etc pieces of flair.

I don't even really care if the project has CI as a badge in the README, because GitHub already surfaces that knowledge in places where it is much more useful (Pull Requests and Commit Lists).

Wow, the first readme linked is horribly ugly and provides no context above the fold. It looks like the zodiac killer’s rear bumper.

https://github.com/zold-io/zold

> Changelog [...] is something from Pre-GitHub time. I would recommend you rely on the "releases" tab

> GitHub has a special tab in each repository, which is called “contributors.” There is absolutely no reason to reproduce the list in the README file.

Why would you tie yourself to github like that?

We super need these kind of content, in Portuguese

Reply on news.ycombinator.com