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

**URL:** https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354
**Category:** Elasticsearch
**Created:** [January 15, 2013, 5:01pm UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354 "2013-01-15T17:01:12Z")
**Posts on this page:** 14
**Page:** 1

<div class="post-metadata">

### Author: ![Justin\_Treher](https://sea2.discourse-cdn.com/elastic/user_avatar/discuss.elastic.co/justin_treher/32/45243_2.png) [@Justin\_Treher](https://discuss.elastic.co/u/Justin_Treher)
#### Post date: [January 15, 2013, 5:01pm UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/1 "2013-01-15T17:01:12Z")

</div>

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.

--

---

<div class="post-metadata">

### Author: ![polyfractal](https://sea2.discourse-cdn.com/elastic/user_avatar/discuss.elastic.co/polyfractal/32/48162_2.png) [@polyfractal](https://discuss.elastic.co/u/polyfractal)
#### Post date: [January 15, 2013, 5:30pm UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/2 "2013-01-15T17:30:25Z")

</div>

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](mailto: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.

--

---

<div class="post-metadata">

### Author: ![Ivan](https://avatars.discourse-cdn.com/v4/letter/i/df788c/32.png) [@Ivan](https://discuss.elastic.co/u/Ivan)
#### Post date: [January 15, 2013, 5:39pm UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/3 "2013-01-15T17:39:00Z")

</div>

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/](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.com](mailto:zacharyjtong@gmail.com)wrote:

> 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](mailto: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.
> > 
> > --

--

---

<div class="post-metadata">

### Author: ![ryanogle](https://sea2.discourse-cdn.com/elastic/user_avatar/discuss.elastic.co/ryanogle/32/2404_2.png) [@ryanogle](https://discuss.elastic.co/u/ryanogle)
#### Post date: [January 16, 2013, 5:28am UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/4 "2013-01-16T05:28:18Z")

</div>

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](mailto: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.

--

---

<div class="post-metadata">

### Author: ![otisg](https://sea2.discourse-cdn.com/elastic/user_avatar/discuss.elastic.co/otisg/32/492_2.png) [@otisg](https://discuss.elastic.co/u/otisg)
#### Post date: [January 18, 2013, 3:21am UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/5 "2013-01-18T03:21:23Z")

</div>

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

Also, have a look  
at [Elastic — The Search AI Company | Elastic](http://www.elasticsearch.org/community/contributing-site.html)

## Otis

ELASTICSEARCH Performance Monitoring - [Sematext Monitoring | Infrastructure Monitoring Service](http://sematext.com/spm/index.html)

On Tuesday, January 15, 2013 12:01:12 PM UTC-5, [jtr...@gmail.com](mailto: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.

--

---

<div class="post-metadata">

### Author: ![Sergey\_Rodovinsky](https://avatars.discourse-cdn.com/v4/letter/s/51bf81/32.png) [@Sergey\_Rodovinsky](https://discuss.elastic.co/u/Sergey_Rodovinsky)
#### Post date: [January 18, 2013, 4:01am UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/6 "2013-01-18T04:01:47Z")

</div>

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](mailto: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.

--

---

<div class="post-metadata">

### Author: ![polyfractal](https://sea2.discourse-cdn.com/elastic/user_avatar/discuss.elastic.co/polyfractal/32/48162_2.png) [@polyfractal](https://discuss.elastic.co/u/polyfractal)
#### Post date: [January 18, 2013, 11:53am UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/7 "2013-01-18T11:53:37Z")

</div>

> For what it's worth, all ES content is searchable at  
> [http://search-lucene.com/](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](http://www.elasticsearch.org/community/contributing-site.html)
> 
> ## Otis
> 
> ELASTICSEARCH Performance Monitoring - [Sematext Monitoring | Infrastructure Monitoring Service](http://sematext.com/spm/index.html)
> 
> On Tuesday, January 15, 2013 12:01:12 PM UTC-5, [jtr...@gmail.com](mailto: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.

--

---

<div class="post-metadata">

### Author: ![phill](https://avatars.discourse-cdn.com/v4/letter/p/779978/32.png) [@phill](https://discuss.elastic.co/u/phill)
#### Post date: [February 12, 2013, 6:45am UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/8 "2013-02-12T06:45:02Z")

</div>

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...  
🙂 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](mailto:elasticsearch+unsubscribe@googlegroups.com).  
For more options, visit [https://groups.google.com/groups/opt\_out](https://groups.google.com/groups/opt_out).

---

<div class="post-metadata">

### Author: ![Mark\_Harwood1](https://sea2.discourse-cdn.com/elastic/user_avatar/discuss.elastic.co/mark_harwood1/32/101255_2.png) [@Mark\_Harwood1](https://discuss.elastic.co/u/Mark_Harwood1)
#### Post date: [February 12, 2013, 11:28am UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/9 "2013-02-12T11:28:18Z")

</div>

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](mailto:elasticsearch+unsubscribe@googlegroups.com).  
For more options, visit [https://groups.google.com/groups/opt\_out](https://groups.google.com/groups/opt_out).

---

<div class="post-metadata">

### Author: ![polyfractal](https://sea2.discourse-cdn.com/elastic/user_avatar/discuss.elastic.co/polyfractal/32/48162_2.png) [@polyfractal](https://discuss.elastic.co/u/polyfractal)
#### Post date: [February 12, 2013, 12:44pm UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/10 "2013-02-12T12:44:11Z")

</div>

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...  
> 🙂 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](mailto:elasticsearch+unsubscribe@googlegroups.com).  
For more options, visit [https://groups.google.com/groups/opt\_out](https://groups.google.com/groups/opt_out).

---

<div class="post-metadata">

### Author: ![mattweber](https://sea2.discourse-cdn.com/elastic/user_avatar/discuss.elastic.co/mattweber/32/44940_2.png) [@mattweber](https://discuss.elastic.co/u/mattweber)
#### Post date: [February 12, 2013, 8:01pm UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/11 "2013-02-12T20:01:22Z")

</div>

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/elasticjs/)  
[http://docs.fullscale.co/translator/](http://docs.fullscale.co/translator/)

Thanks,  
Matt Weber

On Tue, Feb 12, 2013 at 4:44 AM, Zachary Tong [zacharyjtong@gmail.com](mailto: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...  
> > 🙂 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](mailto:elasticsearch+unsubscribe@googlegroups.com).  
> For more options, visit [https://groups.google.com/groups/opt\_out](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](mailto:elasticsearch+unsubscribe@googlegroups.com).  
For more options, visit [https://groups.google.com/groups/opt\_out](https://groups.google.com/groups/opt_out).

---

<div class="post-metadata">

### Author: ![Jilles\_van\_Gurp](https://sea2.discourse-cdn.com/elastic/user_avatar/discuss.elastic.co/jilles_van_gurp/32/879_2.png) [@Jilles\_van\_Gurp](https://discuss.elastic.co/u/Jilles_van_Gurp)
#### Post date: [February 13, 2013, 9:59am UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/12 "2013-02-13T09:59:11Z")

</div>

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](mailto: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](mailto:elasticsearch+unsubscribe@googlegroups.com).  
For more options, visit [https://groups.google.com/groups/opt\_out](https://groups.google.com/groups/opt_out).

---

<div class="post-metadata">

### Author: ![kimchy](https://sea2.discourse-cdn.com/elastic/user_avatar/discuss.elastic.co/kimchy/32/44952_2.png) [@kimchy](https://discuss.elastic.co/u/kimchy)
#### Post date: [February 13, 2013, 9:06pm UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/13 "2013-02-13T21:06:35Z")

</div>

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](mailto: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](mailto: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](mailto:elasticsearch+unsubscribe@googlegroups.com).  
> For more options, visit [https://groups.google.com/groups/opt\_out](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](mailto:elasticsearch+unsubscribe@googlegroups.com).  
For more options, visit [https://groups.google.com/groups/opt\_out](https://groups.google.com/groups/opt_out).

---

<div class="post-metadata">

### Author: ![system](https://us1.discourse-cdn.com/elastic/original/3X/1/a/1ac57faf039f6b580b3f104ef42a2a89e41014de.png) [@system](https://discuss.elastic.co/u/system)
#### Post date: [July 6, 2017, 2:51am UTC](https://discuss.elastic.co/t/wow-there-is-some-really-great-documenation-for-es-but/10354/14 "2017-07-06T02:51:33Z")

</div>


