I’m usually loathe to link to Reddit topics, but this one caught my eye.
How often have you landed on a project page and not been able to make
heads or tails of what that software is meant to do? Like the hundreds
of commenters, I feel like it happens frequently (but I’m suspicious of
my own generalization, for what its worth).
Some of the commenters go on to give possible explanations for why, many
pointing to this being a marketing problem—not widespread, but the
assumption being that developers are willing to donate time, yet
marketers (whatever that means) are not. It would be fun to debate
these opinions but I’ll leave that aside for now.
I would guess that this is probably an issue of missing small details.
Some people have trouble describing the function of their work, the
whats and whys, sure, but most developers are capable of including these
details (or other small points like an up-to-date screenshot). What may
be amplifying this problem is the changing demographics and expectations
of the community. Simply put, we (the community) have higher
expectations. We expect if we’re meeting you (the development team) on
your repository or website, that there has been some consideration for
how we can understand and make use of your software.
It is hard to blame the community for feeling that way. There's no real
anger, just mild frustrations—paper cuts, really—that build up overtime
and distort our perceptions about the entire open-source project.
To you, the developer, you’re doing incredible work that everyone
appreciates. Do not be discouraged, instead push a little harder to
include these minor details or be brave enough to ask for help.
To you, the user/marketer/whatever, be brave enough to ask if you can
help adding a screenshot/description or brave enough to ask the
questions, “What does this do? And why does it exist?” Most importantly,
be humble enough to shake off whatever frustrations you have if the
answer (or lack there of) does not include you, despite your best