Wow, there is some really great documenation for ES! But

Elastic Stack Elasticsearch
1

It took me about four days on and off to figure out how to use the
documentation "navigation" (navigation definitely needs quotes there).
Basically, I can fork this thing and rework the TOC and someone will pull
it back in within a reasonable time frame? See, I heard that ES
documentation was just horrible, so I concluded that this is just how it
is, but there really is quite a bit in there once you find it.

My main gripe is the the table of contents hierarchy which just goes all
over the place. It wasn't until I started examining the URL bar and using
that to navigate up that I saw what was going on. Fortunately, the search
is pretty fantastic (!), but that's not really where newbies are going to
start.

--

1 Like
2

Gotta agree. The navigation on the side is very confusing. I usually just
google the topic I need, since the navigation is so unintuitive. Which
made it very hard to learn things as a beginner (since you don't know what
you don't know).

I definitely support any effort to rework the TOC.

On Tuesday, January 15, 2013 12:01:12 PM UTC-5, jtr...@gmail.com wrote:

It took me about four days on and off to figure out how to use the
documentation "navigation" (navigation definitely needs quotes there).
Basically, I can fork this thing and rework the TOC and someone will pull
it back in within a reasonable time frame? See, I heard that ES
documentation was just horrible, so I concluded that this is just how it
is, but there really is quite a bit in there once you find it.

My main gripe is the the table of contents hierarchy which just goes all
over the place. It wasn't until I started examining the URL bar and using
that to navigate up that I saw what was going on. Fortunately, the search
is pretty fantastic (!), but that's not really where newbies are going to
start.

--

3

Elasticsearch's documentation is not all that bad, especially compared to
many other open-source projects. Have you ever seen Lucene's documentation?
Now that's bad. Shay actually had really good documentation for Compass,
his past project: http://www.compass-project.org/docs/2.2.0/reference/html/

The ToC could use some tweaking. Some concepts are grouped together by
their module. However, most developers do not carry about things at the
module level, they just want to get things done. Elasticsearch should get a
summer intern to work on docs!

Cheers,

Ivan

On Tue, Jan 15, 2013 at 9:30 AM, Zachary Tong zacharyjtong@gmail.comwrote:

Gotta agree. The navigation on the side is very confusing. I usually
just google the topic I need, since the navigation is so unintuitive.
Which made it very hard to learn things as a beginner (since you don't
know what you don't know).

I definitely support any effort to rework the TOC.

On Tuesday, January 15, 2013 12:01:12 PM UTC-5, jtr...@gmail.com wrote:

It took me about four days on and off to figure out how to use the
documentation "navigation" (navigation definitely needs quotes there).
Basically, I can fork this thing and rework the TOC and someone will pull
it back in within a reasonable time frame? See, I heard that ES
documentation was just horrible, so I concluded that this is just how it
is, but there really is quite a bit in there once you find it.

My main gripe is the the table of contents hierarchy which just goes all
over the place. It wasn't until I started examining the URL bar and using
that to navigate up that I saw what was going on. Fortunately, the search
is pretty fantastic (!), but that's not really where newbies are going to
start.

--

--

4

I have to agree with this as well. If you spend the time rooting around,
and find the page you want, the documentation is generally very clear and
explanatory. But totally agree that finding the page can be annoying.

On Tuesday, January 15, 2013 9:01:12 AM UTC-8, jtr...@gmail.com wrote:

It took me about four days on and off to figure out how to use the
documentation "navigation" (navigation definitely needs quotes there).
Basically, I can fork this thing and rework the TOC and someone will pull
it back in within a reasonable time frame? See, I heard that ES
documentation was just horrible, so I concluded that this is just how it
is, but there really is quite a bit in there once you find it.

My main gripe is the the table of contents hierarchy which just goes all
over the place. It wasn't until I started examining the URL bar and using
that to navigate up that I saw what was going on. Fortunately, the search
is pretty fantastic (!), but that's not really where newbies are going to
start.

--

5

For what it's worth, all ES content is searchable at
http://search-lucene.com/

Also, have a look
at Elasticsearch Platform — Find real-time answers at scale | Elastic

Otis

ELASTICSEARCH Performance Monitoring - Sematext Monitoring | Infrastructure Monitoring Service

On Tuesday, January 15, 2013 12:01:12 PM UTC-5, jtr...@gmail.com wrote:

It took me about four days on and off to figure out how to use the
documentation "navigation" (navigation definitely needs quotes there).
Basically, I can fork this thing and rework the TOC and someone will pull
it back in within a reasonable time frame? See, I heard that ES
documentation was just horrible, so I concluded that this is just how it
is, but there really is quite a bit in there once you find it.

My main gripe is the the table of contents hierarchy which just goes all
over the place. It wasn't until I started examining the URL bar and using
that to navigate up that I saw what was going on. Fortunately, the search
is pretty fantastic (!), but that's not really where newbies are going to
start.

--

6

Totally agree. 4-5 days before I got how to navigate the documentation.
After that I can find a lot of what I need.

On Tuesday, January 15, 2013 12:01:12 PM UTC-5, jtr...@gmail.com wrote:

It took me about four days on and off to figure out how to use the
documentation "navigation" (navigation definitely needs quotes there).
Basically, I can fork this thing and rework the TOC and someone will pull
it back in within a reasonable time frame? See, I heard that ES
documentation was just horrible, so I concluded that this is just how it
is, but there really is quite a bit in there once you find it.

My main gripe is the the table of contents hierarchy which just goes all
over the place. It wasn't until I started examining the URL bar and using
that to navigate up that I saw what was going on. Fortunately, the search
is pretty fantastic (!), but that's not really where newbies are going to
start.

--

7

For what it's worth, all ES content is searchable at
http://search-lucene.com/

Wow, how have I never seen this before? This is a great resources, thanks
for sharing it!

-Zach

Also, have a look at
Elasticsearch Platform — Find real-time answers at scale | Elastic

Otis

ELASTICSEARCH Performance Monitoring - Sematext Monitoring | Infrastructure Monitoring Service

On Tuesday, January 15, 2013 12:01:12 PM UTC-5, jtr...@gmail.com wrote:

It took me about four days on and off to figure out how to use the
documentation "navigation" (navigation definitely needs quotes there).
Basically, I can fork this thing and rework the TOC and someone will pull
it back in within a reasonable time frame? See, I heard that ES
documentation was just horrible, so I concluded that this is just how it
is, but there really is quite a bit in there once you find it.

My main gripe is the the table of contents hierarchy which just goes all
over the place. It wasn't until I started examining the URL bar and using
that to navigate up that I saw what was going on. Fortunately, the search
is pretty fantastic (!), but that's not really where newbies are going to
start.

--

8

On 1/15/2013 9:30 AM, Zachary Tong wrote:

Gotta agree. The navigation on the side is very confusing. I usually
just google the topic I need,

The navigation is "light" and the cross connectivity could use lots of
work. This is hyper-text people, just connect everything to everything,
so where ever someone is reading they can get back to something that
defines what they missed. The weird pruned tree structure definitely is
not it strong point.

But that said, Zachary uses Google to search ES?! Come now, use ES to
search ES documentation. Use the search bar provided at the top of all
pages.

I still have a plan to help in the area of modules and index modules
documentation, if I could just figure out how to define them myself...
:slight_smile: The module page itself is literally blank! Its menu leads to all
the types of modules, but never a page showing a module example, or
pointing to an example, nor the mention after licking through modules
that modules go in the elasticsearch.yml file (or elasticsearch.json)
file or how the index module settings can be defining an index, but
don't ask me yet what that looks like in yaml and Json.

Just a English language Note

The construction:
"The {noun} allows to {verb} " IS NOT ENGLISH
Instructions without an explicit "you" are bad enough, but also in some
indiomatic form translated from what language I'm not sure is just
jarring to read!
"You can {verb} by using the {noun} ..." and other forms all make the
person doing the action more obvious.

Also let's agree to speak directly to the reader as "you" not as "we".
I don't really know or care what you want to do.

-Paul

--
You received this message because you are subscribed to the Google Groups "elasticsearch" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elasticsearch+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

9

My main gripe is the CSS. My eyeballs ache after any time spent reading
with that green background.

Out of frustration I just installed the StyleBot plugin to do some CSS
tweaks and that gave me an even-less soothing blue-screen-of-death. Hmm.

--
You received this message because you are subscribed to the Google Groups "elasticsearch" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elasticsearch+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

10

Haha, I've been using ES for about a year now and only noticed the search
bar at the top of the docs two weeks ago. XD To be fair, sometimes it's
just easier to mash Ctr-T in Firefox and start typing "elasticsearch
" into the FF searchbar.

-Zach

On Tuesday, February 12, 2013 1:45:02 AM UTC-5, P Hill wrote:

On 1/15/2013 9:30 AM, Zachary Tong wrote:

Gotta agree. The navigation on the side is very confusing. I usually
just google the topic I need,

The navigation is "light" and the cross connectivity could use lots of
work. This is hyper-text people, just connect everything to everything,
so where ever someone is reading they can get back to something that
defines what they missed. The weird pruned tree structure definitely is
not it strong point.

But that said, Zachary uses Google to search ES?! Come now, use ES to
search ES documentation. Use the search bar provided at the top of all
pages.

I still have a plan to help in the area of modules and index modules
documentation, if I could just figure out how to define them myself...
:slight_smile: The module page itself is literally blank! Its menu leads to all
the types of modules, but never a page showing a module example, or
pointing to an example, nor the mention after licking through modules
that modules go in the elasticsearch.yml file (or elasticsearch.json)
file or how the index module settings can be defining an index, but
don't ask me yet what that looks like in yaml and Json.

Just a English language Note

The construction:
"The {noun} allows to {verb} " IS NOT ENGLISH
Instructions without an explicit "you" are bad enough, but also in some
indiomatic form translated from what language I'm not sure is just
jarring to read!
"You can {verb} by using the {noun} ..." and other forms all make the
person doing the action more obvious.

Also let's agree to speak directly to the reader as "you" not as "we".
I don't really know or care what you want to do.

-Paul

--
You received this message because you are subscribed to the Google Groups "elasticsearch" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elasticsearch+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

11

Also the Elastic.js documentation is very complete for queries,
filters, and facets. This documentation can be helpful even for
someone using the REST api directly, especially when used in
conjunction with the query translator that converts javascript to the
REST request.

http://docs.fullscale.co/elasticjs/
http://docs.fullscale.co/translator/

Thanks,
Matt Weber

On Tue, Feb 12, 2013 at 4:44 AM, Zachary Tong zacharyjtong@gmail.com wrote:

Haha, I've been using ES for about a year now and only noticed the search
bar at the top of the docs two weeks ago. XD To be fair, sometimes it's
just easier to mash Ctr-T in Firefox and start typing "elasticsearch
" into the FF searchbar.

-Zach

On Tuesday, February 12, 2013 1:45:02 AM UTC-5, P Hill wrote:

On 1/15/2013 9:30 AM, Zachary Tong wrote:

Gotta agree. The navigation on the side is very confusing. I usually
just google the topic I need,

The navigation is "light" and the cross connectivity could use lots of
work. This is hyper-text people, just connect everything to everything,
so where ever someone is reading they can get back to something that
defines what they missed. The weird pruned tree structure definitely is
not it strong point.

But that said, Zachary uses Google to search ES?! Come now, use ES to
search ES documentation. Use the search bar provided at the top of all
pages.

I still have a plan to help in the area of modules and index modules
documentation, if I could just figure out how to define them myself...
:slight_smile: The module page itself is literally blank! Its menu leads to all
the types of modules, but never a page showing a module example, or
pointing to an example, nor the mention after licking through modules
that modules go in the elasticsearch.yml file (or elasticsearch.json)
file or how the index module settings can be defining an index, but
don't ask me yet what that looks like in yaml and Json.

Just a English language Note

The construction:
"The {noun} allows to {verb} " IS NOT ENGLISH
Instructions without an explicit "you" are bad enough, but also in some
indiomatic form translated from what language I'm not sure is just
jarring to read!
"You can {verb} by using the {noun} ..." and other forms all make the
person doing the action more obvious.

Also let's agree to speak directly to the reader as "you" not as "we".
I don't really know or care what you want to do.

-Paul

--
You received this message because you are subscribed to the Google Groups
"elasticsearch" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to elasticsearch+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups "elasticsearch" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elasticsearch+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

12

The Elasticsearch documentation definitely covers most of the feature set,
which is good. That being said, there is lots of room for improvement and I
have definitely struggled with figuring out what should be very basic
things on a number of occasions.

The structure is definitely a massive problem for new users. Basically what
they need to know is scattered over dozens of pages. These pages are full
of code fragments that are not complete working examples but small
fragments of json that require non trivial other bits of other json that
you have to hunt together over mostly unlinked other pages. In many cases
it is actually quite ambiguous what you are supposed to do. It took me
several days to make sense of the query DSL because of this: everything I
tried failed with some error and Elasticsearch is not forgiving or
particularly helpful when you do things wrong.

While trying to figure out the geo_shape part of Elasticsearch I actually
found out that the documentation was wrong as well (and submitted a fix):
one of the documented field names had been renamed and several of the json
fragments did not actually parse due to missing commas and other typing
mistakes.

For geo_shape alone, there are at least three relevant pages: one for the
mapping, one for querying, and one for filter queries. The examples on
these pages don't line up. What would have been helpful for this particular
feature would have been a single page about how to work with geo_shape in
Elasticsearch that includes:

  • sample documents with the different geo_shape types
  • a working mapping for these documents
  • a few working queries. I have actually yet to find a way to get this
    working at all: it consistently fails for me with a max clauses error, I
    suspect this is broken currently. If not please fix the documentation.
  • a few working filter queries (this actually works)
  • the current reference documentation for the different field names in the
    json

I think restructuring the documentation around working code examples like
this would be a good idea for most major features in Elasticsearch. Mostly
this would actually help maintaining the documentation as well. If you have
complete code samples, people are going to notice when they don't work.
Also having a single page to fix instead of three or more helps developers
as well when they are working on the code and documentation.

Jilles

On Tuesday, January 15, 2013 6:01:12 PM UTC+1, jtr...@gmail.com wrote:

It took me about four days on and off to figure out how to use the
documentation "navigation" (navigation definitely needs quotes there).
Basically, I can fork this thing and rework the TOC and someone will pull
it back in within a reasonable time frame? See, I heard that ES
documentation was just horrible, so I concluded that this is just how it
is, but there really is quite a bit in there once you find it.

My main gripe is the the table of contents hierarchy which just goes all
over the place. It wasn't until I started examining the URL bar and using
that to navigate up that I saw what was going on. Fortunately, the search
is pretty fantastic (!), but that's not really where newbies are going to
start.

--
You received this message because you are subscribed to the Google Groups "elasticsearch" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elasticsearch+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

13

Fellows, thanks for the feedback!.

I can tell you that we are actively working on a whole revamp to our documentation, specifically addressing all the needs mentioned here (so we are on a good track) and then a bit more. Its going to take some time, we need to get the infra in place and some core content first, and also it has an interesting twist (suspense! : ) ). Hopefully it will come out pretty soon, and then we can start and iterate from there.

On Feb 13, 2013, at 10:59 AM, Jilles van Gurp jillesvangurp@gmail.com wrote:

The Elasticsearch documentation definitely covers most of the feature set, which is good. That being said, there is lots of room for improvement and I have definitely struggled with figuring out what should be very basic things on a number of occasions.

The structure is definitely a massive problem for new users. Basically what they need to know is scattered over dozens of pages. These pages are full of code fragments that are not complete working examples but small fragments of json that require non trivial other bits of other json that you have to hunt together over mostly unlinked other pages. In many cases it is actually quite ambiguous what you are supposed to do. It took me several days to make sense of the query DSL because of this: everything I tried failed with some error and Elasticsearch is not forgiving or particularly helpful when you do things wrong.

While trying to figure out the geo_shape part of Elasticsearch I actually found out that the documentation was wrong as well (and submitted a fix): one of the documented field names had been renamed and several of the json fragments did not actually parse due to missing commas and other typing mistakes.

For geo_shape alone, there are at least three relevant pages: one for the mapping, one for querying, and one for filter queries. The examples on these pages don't line up. What would have been helpful for this particular feature would have been a single page about how to work with geo_shape in Elasticsearch that includes:

  • sample documents with the different geo_shape types
  • a working mapping for these documents
  • a few working queries. I have actually yet to find a way to get this working at all: it consistently fails for me with a max clauses error, I suspect this is broken currently. If not please fix the documentation.
  • a few working filter queries (this actually works)
  • the current reference documentation for the different field names in the json

I think restructuring the documentation around working code examples like this would be a good idea for most major features in Elasticsearch. Mostly this would actually help maintaining the documentation as well. If you have complete code samples, people are going to notice when they don't work. Also having a single page to fix instead of three or more helps developers as well when they are working on the code and documentation.

Jilles

On Tuesday, January 15, 2013 6:01:12 PM UTC+1, jtr...@gmail.com wrote:
It took me about four days on and off to figure out how to use the documentation "navigation" (navigation definitely needs quotes there). Basically, I can fork this thing and rework the TOC and someone will pull it back in within a reasonable time frame? See, I heard that ES documentation was just horrible, so I concluded that this is just how it is, but there really is quite a bit in there once you find it.

My main gripe is the the table of contents hierarchy which just goes all over the place. It wasn't until I started examining the URL bar and using that to navigate up that I saw what was going on. Fortunately, the search is pretty fantastic (!), but that's not really where newbies are going to start.

--
You received this message because you are subscribed to the Google Groups "elasticsearch" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elasticsearch+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups "elasticsearch" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elasticsearch+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.