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
contributions?
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.
I have it cloned myself although never got around to contributing. I should
do that as I'd rather Shay spent as much of his time writing this magic
project than writing documentation!!
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
contributions?
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.
OK, then it's my ignorance about the process. Maybe my request, then, is for
more community docs contributions. Especially guides! I'll start
contributing myself where I can.
I have it cloned myself although never got around to contributing. I should
do that as I'd rather Shay spent as much of his time writing this magic
project than writing documentation!!
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
contributions?
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.
Apache, Apache Lucene, Apache Hadoop, Hadoop, HDFS and the yellow elephant
logo are trademarks of the
Apache Software Foundation
in the United States and/or other countries.