-
Notifications
You must be signed in to change notification settings - Fork 24.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[DOCS] Add concepts section to analysis topic #50801
Conversation
This helps the topic to better match the structure of our machine learning docs, e.g. https://www.elastic.co/guide/en/machine-learning/7.5/ml-concepts.html This PR only includes the 'Anatomy of an analyzer' page as a 'Concepts' child page, but I plan to add other concepts, such as 'Index time vs. search time', with later PRs.
Pinging @elastic/es-docs (>docs) |
Pinging @elastic/es-search (:Search/Analysis) |
@@ -1,5 +1,5 @@ | |||
[[analyzer-anatomy]] | |||
== Anatomy of an analyzer | |||
=== Anatomy of an analyzer |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No substantive changes were made to this page. Simply adjusted headings and attributes so they would display normally. I plan to do an overhaul of this page in an upcoming PR.
|
||
This section explains the fundamental concepts of text analysis in {es}. | ||
|
||
* <<analyzer-anatomy>> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a bit sparse at the moment, but I plan to move some of the index/search time analysis content here from the top-level Analysis page in an upcoming PR.
What is the value in introducing another nav layer with the "concepts" bucket? I feel like this approach is going to proliferate more content-free nav pages that users land on and have to click through. For the ML book, it's just one page, but if we do this throughout the ES ref, we're going to have a bunch of concept link-farms. If we want to adopt a "page per concept" model (for SEO?), is there a reason that they aren't just part of the Overview section? I sort of feel like introducing the concepts that are central to a feature is the whole point of the overview sections. I can see the value in having a consistent approach across the doc set, but this feels like it's inclined to propagate patterns that we know are problematic: content-free pages and a lot of short pages. |
Thanks for your feedback @debadair. Responses below.
It explicitly labels conceptual docs, differentiating them from other types of documentation. Making this explicit helps guide our users. It lets them know what kind of content to expect in the bucket. It also helps guide contributors, who know what type of content to place here, and serves as a quick indicator of whether content for a particular concept already exists.
This is a feature, not a bug. If a user lands on this page, they are likely looking for broad information ("Elasticsearch analysis concepts") or the content they want likely doesn't exist. This nav page helps orient the user in both cases.
It's two pages: Regardless, I'm confused about why this would be permissible as a one-off but not a pattern. Bad practice is bad practice?
There are a few reasons:
Aside from anecdotes, how do we know navigation pages are problematic? Anecdotally, I've heard feedback both from users and Elastic leadership that our docs often contain "walls of text." As stated above, I think the nav page gives users and contributors good guideposts. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM!
Another thing @szabosteve and I have considered is using metadata to indicate content types, so that when we have a better navigation structure, users can filter on different content types. We aren't at the implementation stage yet, but I've played around with inserting this type of metadata in elastic/stack-docs#802 |
This helps the topic better match the structure of our machine learning docs, e.g. https://www.elastic.co/guide/en/machine-learning/7.5/ml-concepts.html This PR only includes the 'Anatomy of an analyzer' page as a 'Concepts' child page, but I plan to add other concepts, such as 'Index time vs. search time', with later PRs.
This helps the topic better match the structure of our machine learning docs, e.g. https://www.elastic.co/guide/en/machine-learning/7.5/ml-concepts.html This PR only includes the 'Anatomy of an analyzer' page as a 'Concepts' child page, but I plan to add other concepts, such as 'Index time vs. search time', with later PRs.
Thanks @szabosteve! |
This helps the topic better match the structure of our machine learning docs, e.g. https://www.elastic.co/guide/en/machine-learning/7.5/ml-concepts.html This PR only includes the 'Anatomy of an analyzer' page as a 'Concepts' child page, but I plan to add other concepts, such as 'Index time vs. search time', with later PRs.
This helps the topic better match the structure of our machine learning docs, e.g. https://www.elastic.co/guide/en/machine-learning/7.5/ml-concepts.html This PR only includes the 'Anatomy of an analyzer' page as a 'Concepts' child page, but I plan to add other concepts, such as 'Index time vs. search time', with later PRs.
Adds a new 'Concepts' page to the analysis topic.
This helps the topic to better match the structure of
our machine learning docs, e.g.
https://www.elastic.co/guide/en/machine-learning/current/ml-concepts.html
This PR only includes the 'Anatomy of an analyzer' page as a child page,
but I plan to add other concepts, such as 'Index time vs. search time',
with later PRs.