cue-lang / docs-and-content

A place to discuss, plan, and track documentation on cuelang.org
6 stars 1 forks source link

A landing page and concept guide for cue-vet #125

Open jpluscplusm opened 6 months ago

jpluscplusm commented 6 months ago

In https://cuelang.org/cl/1193603 I attempted to quickly address https://cuelang.slack.com/archives/CLT4FD7KP/p1711532252834579, which was caused by a user not being aware that cue vet can resolve constraints from packages, not just individual files.

Whilst we work out the best approach for the built-in cue help texts in this space, on cuelang.org We should publish a primer landing page and a concept guide for cue vet that (between them), amongst other things, pushes readers towards package-based constraint resolution, not file-based.

Given the non-task-specific nature of this pair of pages, I suggest that the reference hierarchy gains the "landing page", suitable for receiving inbound links from anywhere on the site, which summarises the command and points onwards to relevant documentation - including the more expansive "things you can do with cue vet" concept guide.

I propose we:

This scheme leaves us with a good template to replicate for other cue subcommands in the future - and other top-level commands like cuepls, as well, if so desired.

myitcv commented 6 months ago

but it

Looks like this sentence was left unfinished.

As I mentioned offline.

If we do it for vet, we need to do it for all commands (otherwise we end up saying "and take a look at vet to see how to do X"). cue help inputs is the canonical reference. I'm minded to think we need better examples on cuelang.org that are richer than the cue help text. Perhaps a single page with examples, using different commands to drive the point home, of the various permutations of inputs. Rather than trying to create a table test of permutations for each command in each help text or a documentation page specific to each command. And then link to this helpful page from cue help inputs and the related content of any page that mentions cue vet, cue export etc.

jpluscplusm commented 5 months ago

but it

Looks like this sentence was left unfinished.

I'm not sure what I was going to say, there. I'm going to update this issue to track being the cue vet reference page that I believe we need, regardless of any changes we make to cue help vet/inputs/etc.

As I mentioned offline.

If we do it for vet, we need to do it for all commands (otherwise we end up saying "and take a look at vet to see how to do X"). cue help inputs is the canonical reference. I'm minded to think we need better examples on cuelang.org that are richer than the cue help text. Perhaps a single page with examples, using different commands to drive the point home, of the various permutations of inputs. Rather than trying to create a table test of permutations for each command in each help text or a documentation page specific to each command. And then link to this helpful page from cue help inputs and the related content of any page that mentions cue vet, cue export etc.

I've tracked this in https://github.com/cue-lang/docs-and-content/issues/144.