Out of curiosity, did ES also redo the java api documentation as well?
Google search doesn't seem to have a concrete hit pointing to the documentation I used to find few months ago.
Is there such a doc that has the comprehensive java api calls with example?
The old one was really difficult cuz it was very incomplete, hence I kind of gave up waiting for the doc to be completed.
The new site I am finding today is this one:
This doc is really useless. All I want to find is how to determine if an index exists from java code using the new api.
I can't seem to get a clear answer...
Apologies in advance for the moan. I know there's been a lot of work on the docs, but it's caused real problems.
I'm also having a really hard time navigating the new documentation site. I'm training up several students in preparation for the Elastic Certified Engineer exam, and we're having to schedule time to go through everything and memorise where the different topics are.
For example, I was trying to find the main page covering ingest pipelines. I eventually found it under Manage Data -> Ingestion -> Transform and enrich data -> Elasticsearch ingest pipelines. There are way too many clicks needed to get to this page; it used to be a link in its own right in the Elasticsearch docs.
I've always told students to use the search when looking up documentation; especially during the exam. The worst part of this change is that it's impossible to find that page using the search. Even using the exact name of the page - Elasticsearch ingest pipelines - the top hit is for serverless ingest pipelines, and actually gives a 404 if you follow the link. The page I'm looking for doesn't appear on the first two pages of results. Even when filtering down to just Elasticsearch documentation, it's still not there.
I'm sure there was a reference page for the ingest pipeline API but I can't find it at all now. The processor reference is in the Reference section, but there's nothing about pipelines. The processor reference page also doesn't come back in a search for the exact name of the page.
We're trying to get to grips with it but we're really, really not having a good time. We can use Google in the field, but students sitting the certification exams are in real trouble because they can't use Google. With the search as broken as it is, they need to memorise where pages are. Frankly, they already have enough on their plate.
@bmorelli25 - Brandon, brace yourself, that reads like powerpoint BS aimed at management. Reference documentation is not a 3-act play. It's just not. No engineer or developer is following a "narrative pathway" when searching/looking at technical documentation. Internally you might think more that way, thinking in terms of "User Stories" when developing the product is understandable. But ... IMvHO it is not the best fit here.
There IS a case for introductions/guides - basics of a product, prerequisites and prep, step 1, then step 2, and so on. But that's not even close to the majority use case of detailed technical documentation - which is just finding the specific item(s) you are looking for quickly, the API/setting/whatever clearly described (preferably with examples), and often links to related items.
By the far the worst aspect of the new docs is just the first part, finding stuff. Sadly thats the key part.
It is still a mystery how this was at all released to the public in the current state. Any amount of realistic user testing would as far as I can tell have identified these issues. I know there is a lot of testing that goes into testing the product stack, but it is a shame this does not seem to extend to the documentation.
... just to add to my previous comment - on reflection I didn't make any constructive suggestion. The primary thing I would focus on now is on the organization and search ability of the documentation. The actual content is likely fine, when I've eventually found what I'm looking for I've understood what I've read.
A suggestion is get people reading these forums, and support requests, and maybe on reddit and other platforms too, NOT developers who know everything backwards, but people with entry/mid- level knowledge, and to look at each thread as they come in and ask themselves "what documentation do we have that helps answers this specific question/query, is it readily findable, and would it actually help?".
It took me a while to recognize that the examples on the right side are actually selectable. Also they a third lot of the screen, despite I just want to read the docs. Another thing:
The bold sub titles seem to have the same amount of space/padding to the bottom and to the top, that makes it hard to read. None of the code snippets in the docs seem to have any syntax highlighting.
In general having all the requests in a single big file makes it crazy hard to search for when you are searching for a common parameter. Also, it's hard to identify if I have read all the documentation, because there is always some button to expand like here:
Why is there another show attributes button that I need to expand? If I search for op_type in that above link, the one that is not expanded is not found, so I don't know if it exists - this in combination with this ultra long page makes it super hard to navigate for me.
For me, as a power user of the previous documentation, this is a major downgrade in terms of usability, but even more, in terms of finding what I search for (I usually know very exactly what I search for). I utterly dislike falling back to google, but that is currently my main mode of operation for navigating the new elasticsearch docs.
I have a similar experience, I've used the old documentation a lot, it was how I've learned a lot of things about the stack and how I've prepared myself for the certification, so I consider myself an advanced user, but with this new API documentation it is extremely complicated to find anything.
Even when you find what you want from the API, the format of the page is awful, there is basically no clear separation between the APIs, it looks like an infinite scroll of text on a white canvas, it is hard to read, if you scroll a little more you got lost and also there are missing information compared with the old API docs.
Is it really that complicated to redeploy the old reference under the same interface?
In all honesty, he had to turn to https://web.archive.org to access an older version of the documentation because it was simply more useful and clear. People aren't asking for radical improvements; they just want access to the old documentation in the same interface that already worked well.
If you want it to look more futuristic, go ahead, make some tweaks with CSS, modernize the look if necessary, but don't sacrifice the high-level experience we had. Changing everything to fine-tune something we don't fully understand is risky. We'll always be comparing it with what we already had, and that can lead to loss of time and efficiency.
There's something I was forgetting... and that's probably why so many people value the previous documentation so much:
Each version not only included the API reference, but also real-world usage examples, best practices, and even tricks, all delivered in well-thought-out sections tailored to each use case.
It was much more than a list of endpoints or parameters: it was a living tool that evolved with each release, and that made it truly valuable. It's not just about accessing information, but about learning how to use it better.
It's a bit annoying, considering what Elastic offers for searches. In the image, you can see how I search for keywords in the reference, and Google seems to be the best option. Question: Will I be allowed to use Google in my exam to find documentation more easily? I'm less than a week away and I'm worried.
@iTiago to confirm are you sitting the Elasticsearch Certified Engineer exam? From my memory you should have access to the documentation in the exam. You won't have access to Google (if the format is the same from when I sat it 3 years ago).
Exactly, that's exactly what I'm trying to say. It's not that there's a lack of documentation, it's that there's no efficient way to find what you need within it, especially under time pressure like the exam.
I understand that Google isn't allowed, but that reinforces the need for Elastic to implement a search engine with specific filters, focusing solely on official documentation (even if it's marked as deprecated, because sometimes it's still useful depending on the version you're using).
This is the biggest problem for everyone that would apply to take the certification, you can only rely on the local documentation and the new documentation is bad, it is very difficult to find anything.
There are multiple posts on this thread mentioned it.
We're at our annual engineering offsite this week. The docs are very high on our discussion list. I've been bringing your feedback to all the relevant teams and people (and probably beyond).
Unfortunately, this won't be a single overnight fix. And there' a long backstory to this.
But as a first step, we brought faceting back to our API docs. So if you search for reindex or bulk on the Elasticsearch API the results should be a lot better again. Again, one of many steps but we're working on it.
Apache, Apache Lucene, Apache Hadoop, Hadoop, HDFS and the yellow elephant
logo are trademarks of the
Apache Software Foundation
in the United States and/or other countries.
