Hello,
Are there any plans to rolback the changes on the Documentation site and also on the new APIs documentation?
Since the changes it is extremely hard to be able to find anything, they have been bad in terms of User Experience.
I need to manually go back to older version to be able to find the things I want or see them in a better format
Thanks for the feedback! I‘ll bring it up internally.
@xeraa Please have a look at this thread as well. Not sure whether this is all related.
Hi @leandrojmp. Thanks for the feedback!
Our goal with the new documentation site was to make content easier to navigate by removing duplication, organizing it around user goals, and creating clear narrative pathways for users to follow. We've tried to ease the transition by linking heavily between old and new docs, but it sounds like there might be more we can do to improve the experience. If you have time to answer a few questions, it would be really helpful in understanding where we can do better.
Could you share a few specific examples of pages or topics that you’re having trouble finding? Are you looking for new content that isn’t where you’d expect, or trying to locate pages you used to find more easily? In other words, is this mainly a discoverability issue for new-to-you docs or for content you already knew existed?
I'm also curious to better understand where you have the biggest difficulty in finding content. API docs? Reference docs? Narrative docs? All areas?
You mentioned going to the older docs to “see them in a better format.” Can you expand on what you mean by that? Better page design? Better information architecture? Something else?
Totally understand how frustrating it can be when content you previously relied on moves or changes format. Thanks in advance for any additional details you can provide!
@bmorelli25 one of the issues already has a issue created.
It is cases like this: logstash.yml | Elastic Documentation
The width of the page is too small and you can't see everything, columns are hiding and you need to drag the page horizontally to see everything.
This affects other pages like this one: TLS fields | Elastic Documentation
In those cases I need to go back to the other version see them without having to drag the page horizontally every time.
In other pages the markdown table is broken and do not render, like this one: Logstash Directory Layout | Elastic Documentation
The API Page I mentioned is this one: Index | Elasticsearch API documentation
I understand that this is more closely how API documentation should looks like, something like Swagger, but in my experience it looks really confusing, there is no clear separation between the APIs, it feels like a long page with infinite scroll.
Also, one recorrent issue with Elastic documentation is the lack of examples, this new API seems to have even fewer examples.
For example, the Create Index API in the new page is this one: Create an index | Elasticsearch API documentation, you have a couple of examples in the right side, the copy and paste button does not seem to work also.
In the old page the examples are cleary and easier to find, the copy and paste works and it will copy the entire request, not just the payload: Create index API | Elasticsearch Guide [8.18] | Elastic
One big issue is that the width of the documentation page (except the API) is too small, the center column needs to be bigger.
@bmorelli25 a pratical example.
I needed to get some information about the _cat/nodes API, mostly about the options for the columns that it can display, the h query parameter.
In the old documentation there is a list with the options available.
But in the new documentation there is no list with the options available.
The user would need to be an experienced user to look at the example response objects to know that they can use some of those values as the options for the h query parameter.
Will also add:
.container { max-width: 1250px !important;} in styles.css), which reduce text page. Maybe to put on 90%It can be noticed that the documentation is now changed/indexed to the functionality layout instead of the product layout. ChristianD has a good workaround, use Google or AI 
Hi @leandrojmp, thanks again for your feedback. The Logstash directory table is fixed. We'll look into the examples issues (lack of, missing, and copying the entire request).
Thanks @leandrojmp. let me track down _cat/nodes issue.
@Rios thanks for your feedback and suggestions. Is logstash primarily the product you look for? For the last bullet, I'm not sure I understand. Is there missing parameter information (similar to @leandrojmp's feedback on _cat/nodes), is it hard to find, or some other challenge (I'm interpreting the last sentence as a navigation or labeling issue using the left hand navigation tree)? By labeling issue, you were looking by product and couldn't find that in the left navigation?
If I'm not wrong, this is the same thing that I noticed that is adding some confusion.
In the previous version, documentation for different products were separated, now they are all organized by category or something like that.
This is not bad per se, it is just different and may take some time to adapt, but I know exactly what I'm looking for, not sure if the experience for someone new to the stack would be the same.
It seems that the documentation is following a similar approach as the Solution Views in Kibana, personally I do not use the Solution Views, all my deployments are configured to use the Classic view, they add too many unnecessary steps and there are too many things missing.
I made an example for LS. Yes, we need extra 5 or more clicks to reach an article in the left navigation. You should open Elastic Docs | Elastic Docs, then you select Get Started or Manage data, then you need to search&click around until you figure out there is Reference, then again few click to figure out there is Ingestion tools. There you can find LS and beats/EAgent.
For me, "Security" under "Deploy and manage" means Security as the product/SIEM. Maybe rename to Secure environment or components.
Can you add also kibana.yml reference which should be similar as filebeat.reference.yml? Why for Kibana? Because int/ext auditors will always the first check Kibana. Yes there is the main security article, and this and this.
Can you make the hardening guide or the auditor check list for at least Kibana in future? Linux users, internal users, https, which TLS is by default enable, multifactor authentication method, session settings etc. in a single document/article briefly explained and linked to the documentation.
@leandrojmp we just deployed an update to address the page width. Let me know if you are seeing your tables OK now. I'm still looking into the issues.
@Tim_Toyoshima Yeah, just saw it!
Increasing the width completely changed the user experience, it is much better now!
I still prefer the old style. It's very clear and things are easier to find/recognize.
It's really hard to pinpoint exactly the changes that make it bad. The fonts, the layout, the contrast between sections, etc.
It's really unreadable.
As Leandro said, they have fixed the table and increased width, now is much better.
@linkerc would love to hear more. I know you said it was hard to pinpoint. But let me know if anything pops out to you.
The old documentation is by far the best online doc I have ever seen. Easy to find stuff, well organized. The title/subtitle's fonts are very easy to spot from the body. I can scroll up and down quickly and be able to spot the section I'm looking for. The table index on the left makes jumping to different section a breeze. The content presentation/organization is well thought after. Very predictable...
This new style is one of the worst I've ever seen if not the worst.
Online javadoc is one I would use as a bad documentation example. I cringe every time my browser search resulted on that site.
But somehow this new style from Elasticsearch is worse than javadoc (at least for me).
I'm wondering if the content has changed or just the style.
Can you guys bring back the old style/content and have a toggle to switch between the two? Let the users tell you which is better.
I'm purely speaking from my own point of view. It is very obvious the moment I saw this new style that you guys have made it way worse. The first time I saw it I thought it was an April fools joke. Or somebody hacked your site. Or ES got bought or gone out of business and this is a community supported effort. (I am not kidding.)
It's not just the difference in familiarity with the old style. It is objectively worse. Flame rises from within when viewing this new style/content.
This new style is impacting my work flow. It has significantly slowed down my ability to find stuff (due to whatever reasons). It means something when I am actually spending time giving long feedbacks. I have a day job. What I'm trying to convey is that I am not just saying this to hate. I want ES to grow cuz it's very helpful to my work. I am complaining because my ability to do my work is being impacted!
There is basically 2 documentation now, one is the Reference documentaton which can be acccessed here and the other is the API documentation, which can be accessed here.
They used to be one thing, but now are in differente places.
Which one are you having more issues?
Personally I find the new REST API documentation pretty bad, I cannot find things there anymore, I saved the bookmark of the old version and use it instead, this one.
second one. The API.
And the link your provided for the old version is the one I declared to be the best documentation ever.
© 2020. All Rights Reserved - Elasticsearch
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.