User contributions to docs

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

User contributions to docs

Eric Mill
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
Reply | Threaded
Open this post in threaded view
|

Re: User contributions to docs

Paul Loy
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 <[hidden email]> 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
[hidden email]
http://uk.linkedin.com/in/paulloy
Reply | Threaded
Open this post in threaded view
|

Re: User contributions to docs

Benjamin Devèze
In reply to this post by Eric Mill
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.
Reply | Threaded
Open this post in threaded view
|

Re: User contributions to docs

Eric Mill
In reply to this post by Paul Loy
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 <[hidden email]> 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 <[hidden email]> 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
[hidden email]
http://uk.linkedin.com/in/paulloy