6 ms·

I've never understood people that spend so much time making their README pretty with emojis, fancy tables etc. Don't get me wrong, documenting your work is ver

by keyle 6y ago

I've never understood people that spend so much time making their README pretty with emojis, fancy tables etc. Don't get me wrong, documenting your work is very important, but do it efficiently. Github Readme's are turning more and more into developer myspace. Just keep it text, to the point, start with why someone should care, then once they care, show them how to use it. When I see some kind of video embed, it's a huge turn off, I don't want to watch some animation of your typos at high speed, or your fish terminal. "Show me the money". Edit: my point is: spend your time making your code better, sorting, fixing and clear your issues and merge or reject decade old PRs /s

tenaciousDaniel 6y ago
> developer myspace I don't think a better description is possible
- godot 6y ago
  I feel like GitHub has been taking a direction of a "social network for developers" for a while now, so that description is probably accurate.
  - eyelidlessness 6y ago
    It’s been that 100% of its existence.
ulisesrmzroche 6y ago
I’ve never understood hn fascination with boring and ugly plain text sites. Reminds me of the infamous Dropbox comment.
- judge2020 6y ago
  > Reminds me of the infamous Dropbox comment. For reference: https://news.ycombinator.com/item?id=9224 https://news.ycombinator.com/item?id=9224
- SoSoRoCoCo 6y ago
  Because they are reliable and consistent. This isn't a place where novelty is appropriate, IMHO. The IETF nails it with their RFCs, e.g.: https://tools.ietf.org/html/rfc5545 https://tools.ietf.org/html/rfc5545
  - felixfbecker 6y ago
    RFCs have a terrible reading experience. Especially on mobile or on a wide screen.
    - sixstringtheory 6y ago
      You're entitled to your opinion regarding RFC readability, but factually, you can't grep through a video like you can with plaintext. You also can't print out a video and highlight things or write notes in the margins (or do the equivalent with a PDF). Scrubbing back multiple times to catch a quickly spoken word or quickly dismissed graphic is the bane of my experience with such video documentation. To me, that may be a fine superficial introductory experience in some cases, but is a universally terrible one for understanding and reference.
      - thesimon 6y ago
        I don't think anyone would favor a video over a RFC. But already a RFC reader makes it a more pleasant experience than just the raw RFC you linked https://www.rfcreader.com/#rfc5545 https://www.rfcreader.com/#rfc5545
        tdeck 6y ago
        I'm not a huge fan of text-only but I definitely find the original easier to read than this website's version from a contrast perspective. I can't think why they would choose gray text on a gray background.
        SoSoRoCoCo 6y ago
        Ironically, the fact that the reader is even POSSIBLE is because of the neutral format of the source RFC. You sorta shot yourself in the foot there.
- wongarsu 6y ago
  People who love boring and ugly plain text sites are bound to be over-represented on a forum with an absolutely bare-bones plaintext-like design.
  - broberts01 6y ago
    Spittin' facts over here.
- chipotle_coyote 6y ago
  I agree with you in principle -- the "web sites should never do things like choose their own typefaces, line lengths and line spacing" crowd always makes me sigh. However. We're not talking about web sites here, we're talking about README files. They should be absolutely readable and understandable if you're displaying them in a console -- that's arguably one of the underlying tenets of Markdown as it was originally conceived (e.g., that its source be as easily readable as a plain text email or Usenet message is). I like that GitHub renders Markdown documents, but a lot of time when you're mucking around with source, you're looking at, well, the plain document. I think this is a fun hack to demonstrate how you can do ridiculous things in technically-still-Markdown documents, but it's unequivocally not something anyone should actually do in their Markdown documents. :)
sam_bristow 6y ago
It depends on the project for me. If it's a graphical tool a screenshot can help a lot in deciding it of does what I need. If it's a library a quick code snippet can give me a feel of whether it'll be a good fit for my project I do tend to agree about the "Developer MySpace" feel of a lot of repos though.
voxl 6y ago
You're assuming it takes that long to make these things. You're also assuming your perception of the README is how most people consume it. To that end, I'll offer a counter-anecdote, I very much want a README to convey to me how the project is: built, used, and what I should know about contributing to it. For usage, having images and videos for certain tools is priceless.
krimpenrik 6y ago
I have to disagree, for beginner programmers those videos are really help out, and if it's supported by a good text doc, it is a win-win right?
throwaway03857 6y ago
Since I develop addons for blender my readmes contain gifs, video embeds and all the things you undoubtedly hate because that's the most efficient way to communicate what the tools actually do and how to use them. Not everyone develops command line tools.
- pwdisswordfish0 6y ago
  READMEs and markdown in general are supposed to be as legible in plain text form as it is when rendered. But that's something the kinds of people who hang out on GitHub don't seem to give two shits about. Any time a project hosted on GitHub is cloned, chances are high that if you try to open the README, it's going to be filled with line noise that effectively means you must use the rendered view. It's no wonder things like building native support for markdown rendering into apps like VSCode are so desirable. Project authors are treating it like an intermediate form that no one is really ever supposed to look at unless they're going into the markdown to add/fix/change something just before submitting a pull request.
  - eyelidlessness 6y ago
    Yes. And that’s not because people are abusing README.md, but because abusing README.md is the only way for most projects to improve most first impressions for their project.
    - pwdisswordfish0 6y ago
      First of all, even if that were true, it wouldn't matter. If a project author is participating in the culture that involves the compulsion "to improve most first impressions for their project", that's just the toxic culture associated with traditional social media projected into a different venue, except it has a facade of respectability that keeps people from calling it out in the way people call out Instagram bullshit. Secondly, it's not true. Don't care about the deleterious effects that comes from overvaluing social media impressions? Want to take part in that messed up, Black Mirror-esque world anyway? Take all that junk you're shoving into the README and put it on a real landing page. No one is forcing anyone to link people to the GitHub repo for first impressions.
CamperBob2 6y ago
On the other hand, there's nothing lamer than a project that purports to be 20 kinds of awesome, but in order to see so much as a single screenshot, we're expected to spend hours screwing around figuring out how to compile it from scratch. If the project is meant to be shared with the community, the README should contain at least enough rich content to convey what it does.
eyelidlessness 6y ago
A lot of times README doesn’t adequately convey the value of (especially UI-oriented) libraries. And the UX of linking out to formats that do is also terrible (I’m saying this as someone who does a lot of library research on my porch using my phone, constantly forgetting my breadcrumb trail because I’ve been bounced back and forth between the GH app and a few dozen browser tabs). There’s definitely a valid use case for more visually expressive walk up experiences for many code projects that could and IMO should be supported at the repository host level. It doesn’t have to be myspace but it could definitely support more embedded example cases and at least some personality.
Noumenon72 6y ago
Presumably people who use tables, videos, and emojis to communicate have reached for those tools many times over the years, so that the process is no more burdensome than you deciding "I should use a bulleted list here". They probably have macros and keyboard shortcuts to let them communicate fast this way.
inbx0 6y ago
Developer myspace sounds great

by keyle 6y ago

tenaciousDaniel 6y ago

> developer myspace I don't think a better description is possible

godot 6y ago
I feel like GitHub has been taking a direction of a "social network for developers" for a while now, so that description is probably accurate.
- eyelidlessness 6y ago
  It’s been that 100% of its existence.

ulisesrmzroche 6y ago

I’ve never understood hn fascination with boring and ugly plain text sites. Reminds me of the infamous Dropbox comment.

judge2020 6y ago
> Reminds me of the infamous Dropbox comment. For reference: https://news.ycombinator.com/item?id=9224 https://news.ycombinator.com/item?id=9224
SoSoRoCoCo 6y ago
Because they are reliable and consistent. This isn't a place where novelty is appropriate, IMHO. The IETF nails it with their RFCs, e.g.: https://tools.ietf.org/html/rfc5545 https://tools.ietf.org/html/rfc5545
- felixfbecker 6y ago
  RFCs have a terrible reading experience. Especially on mobile or on a wide screen.
  - sixstringtheory 6y ago
    You're entitled to your opinion regarding RFC readability, but factually, you can't grep through a video like you can with plaintext. You also can't print out a video and highlight things or write notes in the margins (or do the equivalent with a PDF). Scrubbing back multiple times to catch a quickly spoken word or quickly dismissed graphic is the bane of my experience with such video documentation. To me, that may be a fine superficial introductory experience in some cases, but is a universally terrible one for understanding and reference.
    - thesimon 6y ago
      I don't think anyone would favor a video over a RFC. But already a RFC reader makes it a more pleasant experience than just the raw RFC you linked https://www.rfcreader.com/#rfc5545 https://www.rfcreader.com/#rfc5545
      - tdeck 6y ago
        I'm not a huge fan of text-only but I definitely find the original easier to read than this website's version from a contrast perspective. I can't think why they would choose gray text on a gray background.
      - SoSoRoCoCo 6y ago
        Ironically, the fact that the reader is even POSSIBLE is because of the neutral format of the source RFC. You sorta shot yourself in the foot there.
wongarsu 6y ago
People who love boring and ugly plain text sites are bound to be over-represented on a forum with an absolutely bare-bones plaintext-like design.
- broberts01 6y ago
  Spittin' facts over here.
chipotle_coyote 6y ago
I agree with you in principle -- the "web sites should never do things like choose their own typefaces, line lengths and line spacing" crowd always makes me sigh. However. We're not talking about web sites here, we're talking about README files. They should be absolutely readable and understandable if you're displaying them in a console -- that's arguably one of the underlying tenets of Markdown as it was originally conceived (e.g., that its source be as easily readable as a plain text email or Usenet message is). I like that GitHub renders Markdown documents, but a lot of time when you're mucking around with source, you're looking at, well, the plain document. I think this is a fun hack to demonstrate how you can do ridiculous things in technically-still-Markdown documents, but it's unequivocally not something anyone should actually do in their Markdown documents. :)

sam_bristow 6y ago

It depends on the project for me. If it's a graphical tool a screenshot can help a lot in deciding it of does what I need. If it's a library a quick code snippet can give me a feel of whether it'll be a good fit for my project I do tend to agree about the "Developer MySpace" feel of a lot of repos though.

voxl 6y ago

You're assuming it takes that long to make these things. You're also assuming your perception of the README is how most people consume it. To that end, I'll offer a counter-anecdote, I very much want a README to convey to me how the project is: built, used, and what I should know about contributing to it. For usage, having images and videos for certain tools is priceless.

krimpenrik 6y ago

I have to disagree, for beginner programmers those videos are really help out, and if it's supported by a good text doc, it is a win-win right?

throwaway03857 6y ago

Since I develop addons for blender my readmes contain gifs, video embeds and all the things you undoubtedly hate because that's the most efficient way to communicate what the tools actually do and how to use them. Not everyone develops command line tools.

pwdisswordfish0 6y ago
READMEs and markdown in general are supposed to be as legible in plain text form as it is when rendered. But that's something the kinds of people who hang out on GitHub don't seem to give two shits about. Any time a project hosted on GitHub is cloned, chances are high that if you try to open the README, it's going to be filled with line noise that effectively means you must use the rendered view. It's no wonder things like building native support for markdown rendering into apps like VSCode are so desirable. Project authors are treating it like an intermediate form that no one is really ever supposed to look at unless they're going into the markdown to add/fix/change something just before submitting a pull request.
- eyelidlessness 6y ago
  Yes. And that’s not because people are abusing README.md, but because abusing README.md is the only way for most projects to improve most first impressions for their project.
  - pwdisswordfish0 6y ago
    First of all, even if that were true, it wouldn't matter. If a project author is participating in the culture that involves the compulsion "to improve most first impressions for their project", that's just the toxic culture associated with traditional social media projected into a different venue, except it has a facade of respectability that keeps people from calling it out in the way people call out Instagram bullshit. Secondly, it's not true. Don't care about the deleterious effects that comes from overvaluing social media impressions? Want to take part in that messed up, Black Mirror-esque world anyway? Take all that junk you're shoving into the README and put it on a real landing page. No one is forcing anyone to link people to the GitHub repo for first impressions.

CamperBob2 6y ago

On the other hand, there's nothing lamer than a project that purports to be 20 kinds of awesome, but in order to see so much as a single screenshot, we're expected to spend hours screwing around figuring out how to compile it from scratch. If the project is meant to be shared with the community, the README should contain at least enough rich content to convey what it does.

eyelidlessness 6y ago

A lot of times README doesn’t adequately convey the value of (especially UI-oriented) libraries. And the UX of linking out to formats that do is also terrible (I’m saying this as someone who does a lot of library research on my porch using my phone, constantly forgetting my breadcrumb trail because I’ve been bounced back and forth between the GH app and a few dozen browser tabs). There’s definitely a valid use case for more visually expressive walk up experiences for many code projects that could and IMO should be supported at the repository host level. It doesn’t have to be myspace but it could definitely support more embedded example cases and at least some personality.

Noumenon72 6y ago

Presumably people who use tables, videos, and emojis to communicate have reached for those tools many times over the years, so that the process is no more burdensome than you deciding "I should use a bulleted list here". They probably have macros and keyboard shortcuts to let them communicate fast this way.

inbx0 6y ago

Developer myspace sounds great