#I m starting to think that each SDK
cerulean shell
Ship it
manic crypt
I like it, too.
tropic vector
The only downside I see, is that we couldn't generate some automated code example from the same source. But I don't know how much is doable with our current state anyway.
hazy cradle
Codegen is a whole topic of itself 🙂 I think it can be layered on top of everything else. So matter how we set things up now: our codegen tooling will be able to follow. At least I think
By the way my perhaps unpopular take: we should NOT open-source our codegen tooling. Instead we should package it as a service first for our own needs (dogfooding) then later open it to everyone. This has huge strategic implications.
To be discussed 🙂
willow turtle
+1 here as well.. the only "caveat" is that this adds another level of complexity when consuming docs since users could either land into docs either by browsing the top-level general ones or per SDK. On this second case, browsing the docs for a specific SDK will still require a read flow that makes sense. So basically, we'll have to make sure that "general" and "per-sdk" docs are actually flow-consistent.
hazy cradle
There's a bunch of PRs in flight addressing exactly that 👍 I think it will work nicely
dry goblet
I'm going to be the contrarian one for a change 🙂
No strong opinions on this, just a gut feeling: I would be concerned that we end up with some "lesser" SDKs: Someone adds a cool example to Go, someone else improves the docs of Node, while Python becomes outdated
I imagine a future where "no SDK is left behind"
Basically, the Stripe docs approach: docs are "use case first" (how to do X with dagger), and snippets are by language
On the back office, we would ensure that they're consistent at all times. For instance, having a "expected stdout" test file for each doc snippet, with automation compiling/executing each snippet and ensuring that they all output the same stuff -- meaning that if you tweak a chunk of docs but forget to update the Python snippet, CI will prevent merging in the first place
Even then, there should probably be a dedicated "landing" page for each SDK (not everything fits the "tutorial" flow), but those should be low-edit-volume
Maybe it's a pipe dream, and it's not practical to do. But that's my first reaction anyway
hazy cradle
Yeah the Stripe API docs model (note: not other parts of the Stripe docs) comes up a lot, it's really impressive and I agree we should do it. It's a significant amount of work to do, though: not something we could realistically ship for a few weeks at best.
My thinking is that we have a perfect opportunity to line this up (if we are OK with investing the effort): the GraphQL API launch. After all, they are the Stripe API docs. That's where the model makes the most sense.
So, if/when we ship this stripe-style Dagger API doc, with multi-language baked in: I think it can be layered on top of the first gen SDK docs. Meanwhile SDK docs and examples will have plenty of SDK-specific content left to make them complementary.
TLDR: I think we can have both 🙂
timber arch
docs are "use case first" (how to do X with dagger), and snippets are by language
I’ve said as much even in SFO, amen to that.
TLDR: I think we can have both 🙂
Awesome!
willow turtle
I'm going to be the contrarian one for a change 🙂
No strong opinions on this,...
I think Andrea transmitted with a better example what I was referring to in my previous comment about complexity on docs "flow" if we go with a very rigid SDK docs separation. Having snippet-only SDK docs looks like it'll help us better to scale and be more organized in the messaging as it's being outlined here
TLDR: I think we can have both 🙂
Makes sense. Would like to get an idea of how it'd look like 
hazy cradle
I guess I have the same question @willow turtle . Would love to better understand what you're proposing (and whether it changes the short term docs plan)
willow turtle
I guess I have the same question <@336241811179962368> . Would love to better un...
I guess what I'm proposing is to make SDK docs something very structured that's designed to be referenced/embedded by the global dagger docs and not something that could take a shape by its own depending on what that SDK community decides to do. That way, we can add a semi-rigid frame to those docs where users need to follow a specific SDK documentation style so we can make sure that each SDK docs are consistent with the general Dagger narrative on how to accomplish a specific task.
A concrete example would be:
1 - We create a new guide on how to run pipelines in parallel pipelines that lives in the top level docs but declares a "fill it here" block where each SDK needs to implement
2 - Each SDK community contributes to that "fill it here" block
3 - rinse & repeat
That way, the Dagger team can focus on the docs flow/narrative and structure and we simplify that part to SDK developers so they focus on documenting and adding examples of more specific use-cases
hazy cradle
I see what you mean. Yeah that could be cool. Note that Stripe doesn't do this. They do multi-language at the API level which is different.