User contributions to docs


(Eric Mill) #1

Hey all,

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.

-- Eric


(Paul Loy) #2

Hey Eric,

I think Shay already has a process in place for accepting user contributions
to documentation. You can produce pull requests for
https://github.com/elasticsearch/elasticsearch.github.com

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!!

Cheers,

Paul.

On Thu, Sep 22, 2011 at 2:23 PM, Eric Mill kprojection@gmail.com wrote:

Hey all,

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.

-- Eric

--

Paul Loy
paul@keteracel.com
http://uk.linkedin.com/in/paulloy


(Benjamin Dev├Ęze) #3

Hey Eric,

you are right the documentation should be a collective effort.

The elasticsearch website/documentation is already in a Github repo where
people can submit pull requests:
https://github.com/elasticsearch/elasticsearch.github.com

I am not a really big fan about comment sections at the bottom of each page
it can be quickly confusing.

Maybe a FAQ section gathering info from the mailing list would be nice.


(Eric Mill) #4

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.

-- Eric

On Thu, Sep 22, 2011 at 9:30 AM, Paul Loy keteracel@gmail.com wrote:

Hey Eric,

I think Shay already has a process in place for accepting user
contributions to documentation. You can produce pull requests for
https://github.com/elasticsearch/elasticsearch.github.com

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!!

Cheers,

Paul.

On Thu, Sep 22, 2011 at 2:23 PM, Eric Mill kprojection@gmail.com wrote:

Hey all,

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.

-- Eric

--

Paul Loy
paul@keteracel.com
http://uk.linkedin.com/in/paulloy


(system) #5