[Contribution guidelines] Updates syntax quick reference

[natasha-moore-elastic]

Summary

Resolves https://github.com/elastic/docs-content-internal/issues/527.

Updates the syntax quick reference page:

• Updated "More details" links to sentence format
• Converted inline formatting examples to a table
• Updated applies_to guidance for accuracy
• Various text edits for clarity, grammar, and consistency
• Added more commonly used components

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

[github-actions]

Vale Linting Results

Summary: 1 suggestion found

💡 Suggestions (1)

File	Line	Rule	Message
contribute-docs/syntax-quick-reference.md	413	Elastic.WordChoice	Consider using 'efficient, basic' instead of 'simple', unless the term is in the UI.

---

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

[github-actions]

🔍 Preview links for changed docs

• contribute-docs/syntax-quick-reference.md

[marciw]

Converted Syntax/Output dropdowns to tabbed format throughout, for consistency with the Syntax guide

Just to explain why I didn't use tabs initially: readers might want to look at the syntax and output at the same time, and tabs make that impossible. (IMHO the tabs in the full syntax guide have this usability problem too.)

was trying to follow this guidance! 😁 "don't make users switch tabs to compare content"

[theletterf]

Good job! Let's get also a review from @leemthompo and @jmikell821

[theletterf]

I would remove this particular DON'T, since we expect users to browse the site using a JS enabled browser (in most cases). LLMs will see the Mermaid diagram source and interpret it all right.

Can we think of do's and don'ts more focused on diagrams? For example: https://developers.google.com/style/images

[natasha-moore-elastic]

Converted Syntax/Output dropdowns to tabbed format throughout, for consistency with the Syntax guide

Just to explain why I didn't use tabs initially: readers might want to look at the syntax and output at the same time, and tabs make that impossible. (IMHO the tabs in the full syntax guide have this usability problem too.)

was trying to follow this guidance! 😁 "don't make users switch tabs to compare content"

Makes sense, thanks! I've reverted to the dropdowns 👍

[leemthompo]

Changes look good to me, thanks @natasha-moore-elastic.

Thinking about the UX of this page, I wonder if we might:

1. make the syntax dropdowns open by default?
2. Or not use dropdowns for syntax at all?

I suspect 90% of folks will just want to copy/paste the syntax as fast as possible, so feels like the secondary information is very front and centre at moment (i.e. the dos and don'ts are kinda hogging real estate and they are visually very loud)

That said, we might even consider putting the do's and don'ts in a dropdowns too, if we agree that action > learning for most consumers of this page, and allow folks who want to drill down into best practices to open those dropdowns when needed.

Just a few ideas, and TBC I would 100% get an LLM to do this if we think any of these suggestions make sense, because this would be pure manual drudgery :)

[marciw]

Changes look good to me, thanks @natasha-moore-elastic.

Thinking about the UX of this page, I wonder if we might:

Just wanted to mention that in the first version of the quick ref, we were seeing it as an "internal" document, so the do's and don'ts seemed more important. There were/are also some elements (like Headings) where both dropdowns might elicit a reaction of "well, obviously"... :dunce-cap:

So maybe there's not a one-size-fits-all solution, but for sure the audience and scope of the page have changed.