Hacker News Reader

Comment by keyle | Hacker News Reader

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

View on HN

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.

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.

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.

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.

Wow. A little flourish on a GH repo front page (which is also a README, because it’s been both for years) is Black Mirror-esque?

One-liner strawmanning isn't hard.

EDIT:

> which is also a README, because it’s been both for years

What is this even supposed to be a response to?

This isn’t worth my time except to say so.

Right, it was clear by the previous comments that you've figured out that low-effort spurious remarks pay off double since they sap energy from anyone foolish enough to try to address them while costing almost nothing on your end to make.

Not at all. I responded candidly with my own perspective and you took the most uncharitable interpretation and twice (now thrice) treated me as if I was responding as venomously as you are. I have abusive family and exes for that, I don’t need it from strangers.

"Wow."

Yeah okay I’m sorry that I was astonished by that. I don’t know how you made the connection between putting a little style in a README and Black Mirror. You went there very quickly and I didn’t have much to contribute other than surprise. I meant no offense.

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

> Reminds me of the infamous Dropbox comment.

For reference:

https://news.ycombinator.com/item?id=9224

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

RFCs have a terrible reading experience. Especially on mobile or on a wide screen.

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.

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

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.

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.

It would be just as possible if RFCs were written in HTML, like most web standards are. You probably wouldn't even need a reader at that point, but you could easily customize the styling with CSS (even user CSS with a browser extension) or just use the reading mode of your browser.

Now that I consider this, you're right. Semantic HTML was designed exactly for this.

A couple things here:

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.

Who is using video as documentation in their README? I’ve seen them as a marketing introduction or maybe a conference talk the author gave about the project but certainly nothing like a doc site in a video format

I like lightweight minimal styles as much as anyone, but I figure they could have made the PDF a good deal more presentable.

I don't see why the PDF should use the Notepad look - one can be too spartan.

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.

Spittin' facts over here.

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. :)

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.

> developer myspace

I don't think a better description is possible

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.

It’s been that 100% of its existence.

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.

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.

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.

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?

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.

Developer myspace sounds great

Reply on news.ycombinator.com