Docs feedback

[elliotgunton]

We've had feedback on the Hera docs, and we should review/rewrite particular long sections (scripts user guide). The feedback included:

• Have an Argo experts section - a signpost from "Quick Start" for people already familiar with Argo and working with yaml. This could just be "read the walkthrough" because its written from a Python perspective, but also we could have a page that maps Argo yaml concepts to Hera's Python.
• More discoverable examples. The feedback described examples that already exist, or at least parts of different examples that could work together, e.g. with_param using a specific output parameter (not the .result as seen in current examples).
• How to do X in Hera? - A "how to" section with common Argo idioms/patterns
• More discoverable class info (attributes, funcs etc) - intellisense and the API reference have too much to be helpful - requires knowledge of how resources are written in yaml
• Signposting the known issues with linting - if you have linting checks in CICD, they will often fail due to Hera's non-standard syntax/typing.

[elliotgunton]

More discoverable examples

I think the current sidebar layout is working quite well now. Some minor issues like

• overlapping terms, e.g. "Dag With Param Passing" to mean "A DAG where a Parameter is Passed", vs "A DAG using with_param" - we should ensure names are unambiguous
• we should ensure examples are focused in on individual features, e.g. it's not clear what Script Variations is conveying (no args vs multiple args in scripts, could be renamed to script_args? But not sure it's worth calling out in an example)
• Intro text should be more utilised instead of code comments, e.g. Callable Script