elastic / elastic/docs-content

Add “What you’ll learn” section to reference architecture docs for reader orientation

Open
#5,584 0 comments 0 reactions 0 assignees View on GitHub
Team:Admin Team:Developer
Dominant language
No language data
Stars
47
Forks
261
Avg merge
3d 12h
Merged PRs (30d)
116

Description

### Summary
Add a short reader-orientation section (e.g. “What you’ll learn”) to the reference architecture documents, placed after the intro and before the first technical section. This would improve onboarding and give readers a quick overview before diving into details.

### Context
In [this PR](https://github.com/elastic/docs-content/pull/5510) for the GenAI search high-availability reference architecture, reviewers [noted](https://github.com/elastic/docs-content/pull/5510#discussion_r2964788795) that the document jumps quickly into detail with little reader orientation. The suggestion is to add a brief section (something like “What you’ll learn”) that outlines the main topics, such as:

Use cases
Architecture
Hardware spec
Considerations

This would act as both an overview and a simple index.

For consistency, apply the same pattern to both reference architecture documents so they stay aligned and maintain continuity.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.