Improve documentation

[tjovicic]

• explain what exactly happens when running dagger up
• it isn't clear is up commands are ran sequentially or in parallel
• document useful commands like: dagger query, dagger input edit, dagger -l debug up --no-cache

[samalba]

Adding some more items:

Cue concepts

• Explain how to use intermediate (like a temporary variable) key in a config (store intermediate data in a definition to avoid this value to be exported in a dagger query)
• Explain the different between a Cue builtin and a definition (native Cue vs dagger stdlib)

Dagger concepts

• Explain dagger.#Artifact, why are they special, can be a docker image, a local directory of data, etc...
• Explain how to use local code - mapping from local dir to dagger.#Artifact is never perfectly understood after reading the documentation
• Explain dagger.#Op builtin operations
• Explain the pipeline #up system, when to use it and the prefered approach

Maybe we could have a 5 minutes video on the main page that shows the getting started and explain various Cue and dagger concepts. Also it was reported that visual elements (animated gifs?) would help understand certain concepts. For instance, the 3 layers (inputs, computed, plan).

cc @talentedmrjones

[helderco]

Also #1061

[samalba]

Also #1061

Good point, merged both issues.

[Breigner01]

To add some feedback

I personally find that the developer documentation is lacking a lot of stuff.
To compare it to dockerfile's documentation, the developer documentation is really complete and when you look for a certain instruction, you have few sentences to explain what it does and how to use it and to supplement this, there are few examples to show how to use it that truly help understand it all.
I think that dagger lacks that a lot and that makes dagger harder to take in hand.

Another thing missing may be some examples that also show multiple instructions working together.

[aluzzardi]

@samalba @talentedmrjones @gerhard Is this issue still relevant?

[samalba]

Most of those items are no more relevant to Europa but we'll still lack internals doc in the first version, I would keep this for the record until we replace it with something else that is more up to date.

[gerhard]

Is this issue still relevant?

Yes. #1327 (comment)