I find that a lot of project homepages (or GitHub README.md these days) are riding high on "if you're reading this, you already know what this is for" energy.
What I would give for people to approach documentation in a more empathetic way; tell me what something is for, what problem it solves vs other competing solutions such as X or Y, whether it's still the best solution or in maintenance mode because another tool has become dominant.
Give me the tools to construct my own pros and cons matrix, without assuming that I'm an expert. Put five minutes into asking yourself "what questions are people likely to have, even if they aren't sure exactly what to ask" and write that down.
I'll never understand how someone can spend months or years of free time building something, but then actively sabotage it by not making it easy for people to realize that they've found what they are looking for.
It's also really valuable to keep perspective on the different kinds of documentation. https://diataxis.fr/ is a really solid starting point for anyone aspiring to create better docs.
This issue with READMEs in particular has driven me nuts for the decade I've been doing ROS related robotics stuff. So many repos where the only surface clue (i.e. before diving into the code) of what it does is your interpretation of its name.
But I'm pretty sure it's universal, like you allude to. And not just open-source; but at work, too. I feel like I'm the only one in my company that makes PRs to edit the READMEs to explain what a repo is for, and what repos it might relate to. (I was much happier in the past when we had a couple mono-repos; now the trend is every little project gets its own undocumented repo, alas.)
Lately I’ve been asking Cursor “what does the program do?” Was actually pretty helpful as a starting point.
Oh yeah, definitely. Great for my own "throwaway" or rushed projects that I want to revisit, too :D
I echo this sentiment. Whilst I completely understand that developers are doing this in their own time and largely for no other reason than it being a labour of love, it would really help lower the barrier to entry.
Oftentimes when the tool is typically used as part of a useful stack, the other components have documentation that can also be difficult to decode. So it becomes an order of magnitude more difficult to understand.
What I really really want to read in a README is *why* did you build this? The "rationale" section of a README is almost always the most interesting part.
I can read the code, I can understand how it works but I cannot know why you decided to tackle this issue a certain way.
There was a project posted here once that didn't even bother saying what the thing even was!