Add Overview content type #4394
Conversation
Vale Linting ResultsSummary: 2 suggestions found 💡 Suggestions (2)
|
🔍 Preview links for changed docs |
There was a problem hiding this comment.
wondering how we handle for overviews that are a group of concepts under one umbrella - for example, this security overview, which explains security by level. we might give people some doorways into breaking up concepts into multiple H2s if needed for "compound" concepts. in these contexts, next steps don't make a lot of sense, because your next step depends on a selection that you make further up on the page based on what you've learned.
we might want to hint that overviews might be very broad or very shallow, focused more on wayfinding or more on explanation. for example, on the opposite side of the spectrum, we basically just have an intro section and then some links: https://www.elastic.co/docs/deploy-manage/production-guidance
a limitations section might also be useful
There was a problem hiding this comment.
we might want to hint that overviews might be very broad or very shallow, focused more on wayfinding or more on explanation
++ to the sentiment that these pages can vary dramatically. I wonder if it makes sense to have distinct content types for these? The current PR is more targeted towards the explanation end of the spectrum. Would it be useful to have way-finding overview pages (or even call them something like "landing pages") as a standalone type? Or maybe that can be handled in one page here too...
There was a problem hiding this comment.
I think the Overview as presented stands well on its own — I would argue that it's a good type to have. If we feel the need to deviate, we would discuss — it might be that we've been cramming several overviews into one in the past.
There was a problem hiding this comment.
that's definitely true, I don't have a super strong opinion on this one, but it does feel like one of the more nebulous types, because it has a lot of recommended/optional elements so it's more open to variation —but maybe that's just par for this course?
There was a problem hiding this comment.
Would it be useful to have way-finding overview pages (or even call them something like "landing pages") as a standalone type? Or maybe that can be handled in one page here too...
I think that we generally skew a little shallow in terms of explanation on our wayfinding pages, so I like presenting them as overviews. However, at least hinting that the sections can be shorter (maybe with examples of the two ends of the spectrum) feels valuable so people don't feel like they're doing something "wrong" if their pages are at the 10th or 110th percentile of completeness.
| An overview provides conceptual information that helps users understand a feature, product, or concept. It answers two fundamental questions: | ||
|
|
||
| - **What is it?** | ||
| - **How does it work?** |
There was a problem hiding this comment.
And! How does it bring value?
| - Help users navigate to the right content for their needs. | ||
| - Clarify how components, features, or concepts relate to each other. | ||
| - Help users choose between options or understand trade-offs. | ||
|
|
There was a problem hiding this comment.
Also: Inform users how Elastic features and capabilities bring value to their organizations and make their lives easier/improve their workflows.
| When you create overview pages, follow these best practices: | ||
|
|
||
| - **Focus on a single concept:** Each overview should be dedicated to one concept, feature, or topic. If you find yourself explaining a second concept in depth, create a separate overview and link to it. | ||
| - **Lead with user value:** Start by explaining why the feature or concept matters to the user, not just what it does. |
There was a problem hiding this comment.
Here it is. We need to get better at this very important piece.
| - **Keep it conceptual:** Focus on explaining ideas, not on step-by-step instructions. Avoid instructional or reference content. Link to how-to guides and reference pages instead. | ||
| - **Answer the key questions:** Ensure your overview addresses the fundamental questions: What is it? Why does it matter? How does it work? When would I use it? | ||
| - **Use concrete examples:** Abstract concepts become clearer when illustrated with real-world scenarios or use cases. | ||
| - **Provide visual aids:** Diagrams, flowcharts, and architecture illustrations help users grasp complex relationships. |
There was a problem hiding this comment.
And help break up walls of content
|
|
||
| <!-- REQUIRED | ||
|
|
||
| Introduction |
There was a problem hiding this comment.
How prescriptive do we want to be?
I was taught that intros should contain 50 words or fewer in one to two sentences. Best practice is to keep the first sentence to about 25 words to provide just enough information so that users know whether to read on, and so that advanced users can get what they need from the intro and not need to read more.
Also, never repeat the title. For example, an overview with the "Dashboards" title:
- Bad intro-> "Dashboards are collections of panels..."
- Good -> "Analyze your data with dashboards."
There was a problem hiding this comment.
Or maybe we need separate guidance on writing good intros
Summary
This PR adds the Overview content type and its template.
Fixes https://github.com/elastic/docs-team/issues/112
Generative AI disclosure
Tool(s) and model(s) used: Claude Opus 4.5 in Cursor 2 (Agent mode).