Any hope for better documentation on ElasticSearch internals and plugin AIPs in the future?


(Jconwell) #1

I've found the process of learning how to write a plugin for ElasticSearch to be like beating my head with a hammer, on a hot summer day in Texas, while laying on a bed of scorpions. And its mostly tied to the incredible lack of any kind of cohesive developer documentation.

There are a few tutorials, which cover the bare bones basics like creating a custom Token Filter. But anything more complex than that is hard to come by. There are a handful of projects on github that show how to do more creative, complex things, but they also have very little comments or documentation on the hows and whys of using the ElasticSearch api.

In the end, the only thing I can do is just sit down and read the ElasticSearch code base, experimental trial and error to get something to work, and hope I'm doing it right.

Now don't get me wrong, I'm all about reading the source of the API I'm gonna use. But that shouldn't be the only source of information about an API. Especially for a platform as mature and widely used as ElasticSearch.

So what am I asking for? At a min bar, I want basic development documentation. You know...the kind that can get generated from just putting comments in your code correctly? Is that too much to ask? Commented code? The whipped cream on the ElasticSearch pie would be in depth tutorials and explanations on the internals of the code base.

Why is this important? I've read that you guys want ElasticSearch to be more than a search engine, but a platform for text analytics. This is an awesome goal because there really isn't a good standard platform for text analytics. But if you want people to really embrace ElasticSearch as this platform, then they need to be able to understand the internals and get up to speed quickly.

Just my $0.02


(Mark Walkom) #2

Thanks for the feedback and sorry to see you're having such a hard time, we certainly try our hardest to document things as much as we can!

I'll take this up internally and see what we can do about it.


(system) #3