Improving hydra-zen docs

[rsokl]

Here are some ideas for Explanation sections

The importance of hierarchical interfaces for programs

• Wire diagram & modules.
  • Swapping out modules means ripping out cables and rewiring.
  • Supporting multiple modules means maintaining control-flow for your wiring

What is a config?

• yaml, dataclass w/ recursively yaml-serializable fields, omegaconf container
• a config should describe what you will be using in your program
  • configs should not be what you actually use in your program, it should let you make the things that you need and then you forget about them

A basic overview of Hydra and hydra-zen

• What do they do and how do they differ?
• Hydra: compose configs, generate CLI, expose grammar, launch & log
• hydra-zen: make & store configs. Pass configs to functions that aren't designed to accept configs.

Keep frameworks at an arm's length

• yamls are bad, code as configs is good
• Keeping Hydra-specific code to a minimum
  • Don't write weirdo patterns for the sake of a CLI

The Anatomy of a Hydra(zen) app

• Design a task function
• Make and store configs
• Launch

Keen to hear other ideas for improving hydra-zen's docs.

[DirkKuhn]

Hi,

what really helped me understand and use hydra/hydra-zen was this popular hydra-lightning template. Maybe we need something similar for hydra-zen. Here is a more complicated example which I have created. Admittedly, such examples are rather geared towards users which already decided to use hydra-zen.
Additionally, I would be interested how you use hydra-zen to run multiple runs in parallel/distributed.

I must admit that I quite like the yaml format. Although I agree in some cases, for example when you want to populate a list with config groups, it gets hard to understand.

Thank you for your hard work!

[Jackiexiao]

After spending about thirty minutes trying to understand hydra-zen, I find myself still quite confused. As a beginner, I must candidly express that I find the documentation for hydra somewhat challenging to grasp. It appears that the material is not as straightforward as I had hoped for someone at my level.