Since it's unfair to expect Shay and Shay alone to provide perfect
documentation for such a powerful and sophisticated project, how could we
expand the official documentation to more easily accommodate user
I can think of a few solutions, of varying attractiveness:
Allow a user comment section at the bottom of each page, to elaborate and
discuss things (many projects do this). It'd be limited to comments on
existing docs pages, though.
Turn the docs into wiki pages, either with public-but-moderated edit
privileges, or privileges given to deputized community members that emerge
from places like this mailing list.
Move the entire docs over to the Github wiki.
Set up a slightly elaborate thing where the docs are in a Github repo, and
people can submit pull requests with additions and changes to the docs.
Do any of these sound attractive to Shay, and to the community? Some hybrid
of them? Something else entirely?
I bring this up because when I first was introduced to ElasticSearch in
June, I had a lot of trouble navigating the docs, and understanding how to
do various foundational things. Even now that I've been using it in
production for months, I'm hesitant to undertake some of the more
sophisticated optimizations I could do because I perceive, rationally or
not, there to be a large learning curve to doing so, partly because of the
docs. The set of guides and tutorials available now is also pretty minimal
compared to what it could be.