cue-lang / docs-and-content

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

docs/introduction: review and revise #93

Open jpluscplusm opened 4 months ago

jpluscplusm commented 4 months ago

On /docs, we currently advertise docs/introduction as "A great place to start: take a trip through what’s possible with CUE [...]", and this isn't really the case. We'd also like to link to docs/introduction directly from the front page.

We should revise this page so that it's suitable to be the 2nd page that a complete newcomer sees, after scanning down the front page, seeing something like "Get introduced to CUE", and clicking on it before they read the rest of the front page.

This means it needs to reiterate the use-cases and integrations, whilst keeping an eye on the friendliness and approachability of the doc for non-CompSci folks. Other questions include:

We'll answer these whilst writing the doc, and seeing how the page then scans with different approaches.

myitcv commented 4 months ago

reiterate the use-cases

Not just the use cases but also integrations.

myitcv commented 2 months ago

Per @mvdan we should use this update as the basis for cue help - which currently suggests a custom command as the first thing to do with CUE 🤦