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.
EDIT:
> which is also a README, because it’s been both for years
What is this even supposed to be a response to?
For reference:
The IETF nails it with their RFCs, e.g.:
But already a RFC reader makes it a more pleasant experience than just the raw RFC you linked
1) that RFC reader is alright, but it still isn't good on a phone. If you view the PDF version of any RFC on ietf.org, it has a hyperlinked table of contents, so you don't need a javascript version of it like what rfcreader.com provides, and you can store that PDF offline. You can also hit the TXT version of any RFC and it's passable in Safari's Reader View, I'd say better than rfcreader.com (I also tried Reader View on rfcreader.com and it has other issues, so it's like trading one set of problems for another, but I see no clear winner, so for me the tie breaker goes to ietf.org);
2) the OP made the point that text is preferable to video–I happen to agree–and I was responding to the hyperbolic (and again, subjective) pushback regarding "ugly" text, explaining a way that it is still functionally superior to videos (which can have wildly diverse quality issues of their own);
3) I didn't link the RFC, that was someone else.
I don't see why the PDF should use the Notepad look - one can be too spartan.
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. :)
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.
I don't think a better description is possible
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.
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.
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.
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