They 'could' have a paragraph at the beginning to help potential users understand the purpose of the project.
It might seem inconsequential, but maintainers often deal with a lot of angry entitled users and it could be helpful to stay away from language that implies that the people giving away their code for free (and for fun) have any obligation to provide anyone anything.
True on principle, but if an explanation or a screenshot that costs 5 hours to make would prevent replying or even just reading support requests for 6 hours, I would call it a victory.
The problem with the whole OSM ecosystem is that it expects a lot of domain knowledge of technologies, formats, tools, their relations and features, limitations, that is rarely explained well, or explanaitions are often terribly outdated. Feels much like the JavaScript Frontend frameworks for an outsider, it is a lot of effort to get to an overview and understanding, despite the concepts are not new.
Usually this is a sign of a project that isn't ready for a lot of attention. It's very brave and a little bit stupid to offer Open Source to the world (especially without a sustainability plan), if you put a lot of effort into 'marketing' at an early stage you've probably just overpromised to people not focused on that domain, won't be able to deliver, and will burn out, and it will become yet another abandoned project.
Perhaps in a few years, as the project picks up uses and contributors, it will get its own website and support network and be easy to understand and use by "anyone."
I agree, but still 1-2 paragraph about why this was made, what is for laymans, and what it is in terms of OSM ecosystem. Possibly my extrovert self makes it natural to write similar intros to repos I make public. (I even used to blog!)
Anyone looking for this will already be in map/OpenStreetMap context. That people originating from StumbleUpon or a niche little place called ycombinator news are confused is not too surprising tbh: that very likely wasn't the audience they had in mind
Considering the title starts with "Show HN" and that the HN username is very closely tied to the GitHub username, I'm gonna go out on a limb here by saying HN is indeed the target audience.
