Hacker News Reader

Comment by czx4f4bd | Hacker News Reader

This is one of my biggest gripes with a lot of open source [edit: and also non-open source] projects. It's sort of baffling to me when I come across a project that the maintainers clearly want to be used, but there's no clear and concise explanation of what the project is, why you'd want to use it, and how it compares with major alternatives.

View on HN

Do note that this project isn't open source: for something like an editor, this is a bit of a negative for me since it significantly reduces how it can be customized if need be.

Oops. Thanks for the correction. I only lightly skimmed the project page, so I think the "Support 10x Development" header made me assume it was an open source project asking for donations.

That said, I'm not really sure why I specified "open source" since my gripe definitely goes for any software project, and probably doubly so for commercial ones, since those actually need a literal sales pitch to convince potential users of their value proposition.

Point taken. I'm currently working on a new website and I'll try and I'll try and address these issues.

It's simply down to time, I spend most of my time working on making 10x better. Because it's still in Beta I haven't focused on the website much.

Agree. Imagine the free publicity of hitting HN front page.

I've closed countless of them because they don't get to the point once I'm there.

I'm doom scrolling on HN. I click interesting links. I'm not (usually) going to waste 5 minutes on your project just to figure out what it is exactly.

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

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