A big shortcoming I've noticed in the software world is a description of what the product actually does. The assumption always seems to be that you already know the problem being solved, and they try to sell you on why their solution is awesome. As a result, I often hear about a project, look around the site or github README file, see no value to me, and never look at it again. Until months later, when someone I know has actually done something with it and I find out it's actually really cool.
As a result, I'm thinking about starting a "What is X, exactly?" series about software I've used. Open-source is hard enough work as it is, and we as developers don't even have complete documentation or great test coverage yet. But here I am piling on more work. Why?
When you begin a project, it's usually to "scratch your own itch." I'd really like to accomplish <goal>. I can't find a good tool to do <goal>, or I just want to create my own for some reason. <goal> is clear and obvious in my mind.
Just describe <goal>, in human language, in your README. Your project is more likely to be used (and even contributed to), if people know what it does.
Anyone who has ever worked in sales (at least, with any success), knows that you sell the benefits, not the features. Don't tell me the shirt is made of "magicfiber 2.0." Tell me the shirt will never wrinkle or stain. Don't tell me I can set three different alarms on my phone. Tell me I can have different alarms for weekdays and weekends. Stupid examples, but you get my point.
Why am I bothering you with all this? Because you probably made something cool, and I want to know about and use it. I'm missing out on something great, because I don't know it exists. You're missing out on users and contributors, and even new friends. Let's fix that.