3 ms·

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

15 points by yegor256a 8y ago

uira 8y ago
We super need these kind of content, in Portuguese
wutwut5521 8y ago
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 https://github.com/zold-io/zold
jitl 8y ago
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.
- WorldMaker 8y ago
  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).
earenndil 8y ago
> 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?

3 ms·

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

15 points by yegor256a 8y ago

uira 8y ago
We super need these kind of content, in Portuguese
wutwut5521 8y ago
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 https://github.com/zold-io/zold
jitl 8y ago
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.
- WorldMaker 8y ago
  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).
earenndil 8y ago
> 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?