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.^[1]

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.^[2] 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 intentions.

---

1. Without placing blame, I’d assume that “marketers” find it more difficult to assume a role in open-source as opportunities are not as clear for either side as the application of an additional programmer may be. More unlikely for someone without a background in software altogether. ↩︎

2. I think the subtext to this and any “Linux marketing” problem is the same we have communication issues between people and an exacerbated commodity problem (i.e., everyone’s time). ↩︎