CUE Documentation and Content Call 2022-10-11

[Lyoness]

Session to discuss documentation and content plans for cuelang.org and the CUE content ecosystem.

Meeting details

Tuesday 11th October at 1530 UTC

https://meet.google.com/iee-ucgh-rrs

The call has been added to the CUE Community shared calendar

This session will also be recorded for those unable to join us live.

Agenda

• Where we are now
• Where we are headed
• How we get there
• Proposed plan
• Community contributions
• Timeline and key dependencies
• Future Docs Calls
• Q&A

Recording

https://www.youtube.com/watch?v=tuidWYIpD7w

Slides

https://docs.google.com/presentation/d/1F0Qs2ak8fMB0XlGRlgXIGYzJ2bbKfFin_nVi3ZzSCIg/edit?usp=sharing

Follow-up Discussion: #1995

Please reply with any questions/topics you would like to see covered.

[mxey]

I think the topic that is most sorely missing in the existing documentation is what Marcel once dubbed “Effective CUE”: a document about style and best practices. I would be interested in things like:

• when to use definitions vs normal fields vs hidden fields
• whether/when to use PascalCase or camelCase

[cedricgc]

I would like to us close the gap on what a development workflow looks like with CUE.

Right now, the use case is fairly abstract looking at the outside in for the average developer to connect. I think making the case for something like infrastructure management is obvious, but getting from A to B once cue is installed is not.

I would envision it as picking an area (such as CI configuration) and showing what dev/maintenance would look like. That would be setup (module init, installing packages or code gen eg. GitHub Actions definitions), defining workflows idiomatically, then using cue cmd to generate YAML files from the CUE definitions.

[cedricgc]

Documentation on integrating CUE workflows with existing build systems would be helpful.

Many tools (especially in the beginning) will not natively parse CUE, effectively requiring a build step for their configuration where it did not exist before (vs writing YAML files directly). Closing the loop to make "configuration builds" natural is an important step to adoption.

This is relevant to where CUE code will live. Most configuration does not exist in pure "configuration repositories", they are part of some greater application code (usually part of the tooling harness). We should have CUE eval/cmds/gen as a build target in make/bazel/nix or equivalent, where the workflow makes sense.

[Lyoness]

Hi all, we're 30 minutes away from our call, here is the Google Meet link to join.

[Lyoness]

The meeting details above have been edited with links to the slide deck and YouTube recording.

Please submit your content and documentation requests, ideas, discussions, and feedback to #1995