Hacker News Reader

Comment by _kst_ | Hacker News Reader

Agreed. I've seen too many README files that summarize the changes in the latest release without explaining what the project is or what it's for. (I don't have a specific example, which might imply that the problem isn't as bad as I remember it being.)

View on HN

Or you only remember READMEs which stuck with you, the rest fell off the grid.

I can’t even estimate how many hundreds of landing pages I’ve closed without getting what they are about, but cannot remember a single one except $subj^W^W (edit: this one is actually not that bad at a second glance).

The only one that's stuck with me is https://github.com/microsoft/pyright, mainly because I thought it was strange that Microsoft would publish something such a lackluster README. It's not the worst ever, but it lacks a clear sales pitch and a concise explanation of why you'd use it instead of mypy. If you go in without that added context, it's kind of mystifying why it even exists or why you'd use it compared with the alternatives.

That's not quite the kind of thing I'm referring to. The first full sentence of the README tells you what it is: "Pyright is a fast type checker meant for large Python source bases."

I'm referring to READMEs that provide no useful information unless you've already been using previous versions of the product (information that should probably go into a file named something like "Changes").

(And again, I don't have a good example.)

Reply on news.ycombinator.com