Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs feedback #965

Open
elliotgunton opened this issue Feb 19, 2024 · 1 comment
Open

Docs feedback #965

elliotgunton opened this issue Feb 19, 2024 · 1 comment
Labels
type:documentation A documentation update

Comments

@elliotgunton
Copy link
Collaborator

elliotgunton commented Feb 19, 2024

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 elliotgunton added the type:documentation A documentation update label Feb 19, 2024
@elliotgunton
Copy link
Collaborator Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type:documentation A documentation update
Projects
None yet
Development

No branches or pull requests

1 participant