backport of improve dsl docs (#36750)

[fearful-symmetry]

Proposed commit message

manual backport of #36750 because I accidentally closed the PR, which deleted the branch, and the mergify bot can't or won't create a new PR on a new branch.

[botelastic]

This pull request doesn't have a Team:<team> label.

[elasticmachine]

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS

Expand to view the summary

Build stats

• Start Time: 2023-10-05T23:39:08.681+0000

• Duration: 110 min 19 sec

Test stats 🧪

Test	Results
Failed	0
Passed	28478
Skipped	2013
Total	30491

💚 Flaky test report

Tests succeeded.

🤖 GitHub comments

Expand to view the GitHub comments

To re-run your PR in the CI, just comment with:

• /test : Re-trigger the build.

• /package : Generate the packages and run the E2E tests.

• /beats-tester : Run the installation tests with beats-tester.

• run elasticsearch-ci/docs : Re-trigger the docs validation. (use unformatted text in the comment!)