Add FAQ section

[grouville]

We keep getting the same questions from the users. Rather than repeating ourselves, this section aggregates the answers.

We reverted the change for image styling and are now using the Docusaurus default.

Pairs: @gerhard @slumbering
Signed-off-by: guillaume guillaume.derouville@gmail.com

[netlify]

✔️ Deploy Preview for devel-docs-dagger-io ready!

🔨 Explore the source changes: 8ff96a2

🔍 Inspect the deploy log: https://app.netlify.com/sites/devel-docs-dagger-io/deploys/61d6fd467d84b20008332c2e

😎 Browse the preview: https://deploy-preview-1348--devel-docs-dagger-io.netlify.app

[aluzzardi]

I think this is a better fit for the CONTRIBUTING file: https://github.com/dagger/dagger/blob/main/CONTRIBUTING.md

[grouville]

I agree, but the idea was to build the first brick of a more detailed FAQ section:

• How to pass an artifact between execs
• Environment name restrictions atm (no dots)
• Tips on how to debug atm (logs level, query cue tree)
  And the list goes on. I collected some points in the last month, @gerhard wants to help exposing them, this is the first step

[gerhard]

I think this is a better fit for the CONTRIBUTING file: https://github.com/dagger/dagger/blob/main/CONTRIBUTING.md

If we want docs to tie everything together - as @shykes thinks about it - then this is the right place for it. WDYT @shykes?

[shykes]

I think this is a better fit for the CONTRIBUTING file: https://github.com/dagger/dagger/blob/main/CONTRIBUTING.md

If we want docs to tie everything together - as @shykes thinks about it - then this is the right place for it. WDYT @shykes?

I think there could be a FAQ entry asking “How do I contribute to Dagger”, that links to CONTRIBUTING.md. But I wouldn’t recommend removing CONTRIBUTING.md, I believe it has become a convention for that file to exist.

One thing we could do is create a separate docs page that is a mirror of the CONTRIBUTING.md. But it will be extra work to keep them in sync, so not sure it would be worth it.

I defer to @aluzzardi for all this.

[gerhard]

I get it now. The specific FAQ that we have addded is related to contributing, and linking to the CONTRIBUTING.md makes most sense. Are you OK to make that change @grouville?

As a follow-up PR, maybe we should add the top 3 questions that you get asked by users @grouville which are not related to contributions - we already know where those answers need to go.

Thank you @aluzzardi for spotting it first, and @shykes for helping me understand 😉

[shykes]

Following up. It looks like this is really a new entry to CONTRIBUTING.md. In the future we might want to mirror that file to the docs, but that should be handled all at once.

• Assuming my understanding is correct, I’m closing this and ask that you open a PR against CONTRIBUTING.md instead.
• If my understanding is wrong, please let me know and I will re-open!

Thanks

[grouville]

Following up. It looks like this is really a new entry to CONTRIBUTING.md. In the future we might want to mirror that file to the docs, but that should be handled all at once.

• Assuming my understanding is correct, I’m closing this and ask that you open a PR against CONTRIBUTING.md instead.
• If my understanding is wrong, please let me know and I will re-open!

Thanks

Ok, this PR does 3 things:

1. Fix some issues on the doc [optimize the rendering of some images: we reduced the size / resolution of the main image (which was heavy)]
2. Add an FAQ section (which we believe has a place here), even though the content isn't inlined atm
3. Intend to explain how to retrigger the CI atm. Which, you're right, shall be in the contributing.md file

Let me a few days to aggregate some of the FAQ content, so we'll reopen and push directly for (1) and (2).
We'll do (3) in a separate PR, you're right

[shykes]

Thanks for details. No need to wait for 1): that can be its own PR and be merged immediately. Small incremental changes ftw

[gerhard]

All learnings in this PR are relevant, and finding out about the ideal place for this type of content was my first take-away.

A more important take-away is that we prefer smaller PRs. While we had a brief discussion about this during the commit, splitting the changes into separate PRs didn't feel worth doing at the time. This interaction made me realise that we actually prefer that, and going forward we should keep this practice. This is the learning that I will be contributing to CONTRIBUTING.md after I add this comment.

I want to emphasise the importance of learning from doing the wrong thing, and then capturing those learnings so that others learn from it too. Small incremental changes feels like a significant approach to how we contribute, something that is likely to become part of our team's culture. Writing it down, repeating it to the point that it becomes a default for everyone feel worth it. I may be wrong, but this is my key take-away from this interaction. Up & away 🚁