News for hackers. Stuff that matters.

A comment on The YAML Document from Hell. Parent comment

Re:The YAML Document from Hell by IshKebab on Thursday January 12, 2023 @02:27PM (#34359036)
I took another look and eventually found the bit of the website that they should put front and centre in the Tutorial page. Still difficult to navigate (why doesn't the page tree show up on the left?) but it is at least well written and to the point.

The "learn more" button on the front page should link to that, perhaps with a single paragraph giving motivation.

And the main page breaks the fundamental rule of programming languages/formats. Put examples on the front page!

I assumed they hadn't done that because the examples would be too complex or maybe the concepts were too difficult to demonstrate with small examples but having gone through the tutorial that isn't there case at all.

[ Parent | on HN ]
Re:The YAML Document from Hell by GauntletWizard on Thursday January 12, 2023 @04:51PM (#34360767)
Are you talking about https://cuelang.org/docs/tutorials/tour/intro/ ? Even that is a bit light on detail for real usage, while https://github.com/cue-lang/cue/blob/v0.4.3/doc/tutorial/kub... is kinda rambling. I don't think that there's "One true way" to introduce these concepts; How you teach cue to a config-generation novice is very different from someone who's used to using an IDE to generate kubernetes YAML.
[ Parent | on HN ]
Re:The YAML Document from Hell by mirekrusin on Friday January 13, 2023 @03:47AM (#34365366)
Spec [0] is very good + practice with small files.

[0] https://cuelang.org/docs/references/spec

[ Parent | on HN ]
Re:The YAML Document from Hell by GauntletWizard on Saturday January 14, 2023 @06:03PM (#34385006)
I find specs nearly unreadable when trying to first digest a language; While invaluable for advanced usage and implementation, I can't read a BNF-Style Spec and make heads or tails of what's going on unless I also have an annotated example next to it.
[ Parent | on HN ]