(Just thinking aloud, feel free to join)
I doubt that attracting extra attention to certain functions will fix the situation unless it's based on statically significant data, which we don't have.
A FAQ (this is essentially what @pksunkara proposes), in order to be useful, needs to focus reader's attention on the minority of topics that are asked most, leaving everything else out of sight.
To identify these commonly asked topics, we would need to gather significant number of help requests/complaints. So far, we've only had 10 or so. And they are fairly broad; I recall
aliases, yadda, yadda. We don't have the data to write a useful FAQ at this point.
Alternative proposal: encourage users to help each other with simple questions (like, what do I use to express "any of those, but not others?"). I think we should aggressively advertise the gitter chat.
And only if the community haven't come up with anything satisfying, tell them to go to the issue tracker. This should significantly reduce the load for maintainers.
Of course, this doesn't' mean that the doc is perfect and needs no improvement.
I mean, the documentation is mostly fine, it's just there's a lot of it. Users, as @spacekookie pointed out, get drowned in it.
We need... well , ideally, we would need a concise list of... pointers?
It's like, we've already had a road, now we need waymarks.
Also, the point of many of our user being newbies.
Maybe some sort of book describing the process of an application creation.
It should touch on most requested (except, as I said, we don't really know what those are)
requirements. Anything else?
I think we should do both, add a minimal FAQ and encourage users to participate in community chat
So I think an FAQ is a really good idea, and we should look through the docs that already exist and see how they can be made easier to navigate. I feel like maybe reducing the README down to a minimal example that people can just copy and paste in most situations, and then moving stuff into a docs folder tree (or wiki) might be a good idea.
I for one usually end up looking for the same three things that are kinda buried in the hay stack
Or well...markdown stack :P
Shortening the README? Yes please. It's so long and looks so close to a documentation that some (I repeat, not enough data to make actual claims here) people confuse it with the actual documentation/examples.
We can write a FAQ based on experience of our own, and then correct it as the we receive feedback.
I for one usually end up looking for the same three things
I am currently talking to someone about activating the discussions feature for our github repo. Hopefully that might help.