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

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Justin Treher
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.

--
 
 
Reply | Threaded
Open this post in threaded view
|

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

Zachary Tong
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, [hidden email] 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.

--
 
 
Reply | Threaded
Open this post in threaded view
|

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

Ivan Brusic
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 <[hidden email]> 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, [hidden email] 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.

--
 
 

--
 
 
Reply | Threaded
Open this post in threaded view
|

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

ryanogle
In reply to this post by Justin Treher
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, [hidden email] 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.

--
 
 
Reply | Threaded
Open this post in threaded view
|

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

Otis Gospodnetic
In reply to this post by Justin Treher
For what it's worth, all ES content is searchable at http://search-lucene.com/

Also, have a look at http://www.elasticsearch.org/community/contributing-site.html

Otis
--
ELASTICSEARCH Performance Monitoring - http://sematext.com/spm/index.html



On Tuesday, January 15, 2013 12:01:12 PM UTC-5, [hidden email] 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.

--
 
 
Reply | Threaded
Open this post in threaded view
|

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

Sergey Rodovinsky
In reply to this post by Justin Treher
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, [hidden email] 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.

--
 
 
Reply | Threaded
Open this post in threaded view
|

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

Zachary Tong
In reply to this post by Otis Gospodnetic
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




 

Otis
--
ELASTICSEARCH Performance Monitoring - http://sematext.com/spm/index.html



On Tuesday, January 15, 2013 12:01:12 PM UTC-5, [hidden email] 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.

--
 
 
Reply | Threaded
Open this post in threaded view
|

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

phill
In reply to this post by Zachary Tong
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 [hidden email].
For more options, visit https://groups.google.com/groups/opt_out.


Reply | Threaded
Open this post in threaded view
|

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

Mark Harwood
In reply to this post by Justin Treher
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 [hidden email].
For more options, visit https://groups.google.com/groups/opt_out.
 
 
Reply | Threaded
Open this post in threaded view
|

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

Zachary Tong
In reply to this post by phill
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 <topic>" 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 [hidden email].
For more options, visit https://groups.google.com/groups/opt_out.
 
 
Reply | Threaded
Open this post in threaded view
|

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

Matt Weber-2
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 <[hidden email]> 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
> <topic>" 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 [hidden email].
> 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 [hidden email].
For more options, visit https://groups.google.com/groups/opt_out.


Reply | Threaded
Open this post in threaded view
|

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

Jilles van Gurp
In reply to this post by Justin Treher
The elastic search 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 elastic search is not forgiving or particularly helpful when you do things wrong. 

While trying to figure out the geo_shape part of elastic search 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 elastic search 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 elastic search. 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, [hidden email] 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 [hidden email].
For more options, visit https://groups.google.com/groups/opt_out.
 
 
Reply | Threaded
Open this post in threaded view
|

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

kimchy
Administrator
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 <[hidden email]> wrote:

The elastic search 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 elastic search is not forgiving or particularly helpful when you do things wrong. 

While trying to figure out the geo_shape part of elastic search 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 elastic search 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 elastic search. 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 [hidden email].
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 [hidden email].
For more options, visit https://groups.google.com/groups/opt_out.