Dagger Docs 2.0

[marcosnils]

This is a discussion to portray the different conversations and ideas I've been speaking with some of the Dagger team members around giving a second iteration to our docs and getting started experience. The objective is to highlight the current improvement opportunities and present a list of actionable items with the hope to make them issues so we can incrementally improve the whole experience.

The current areas of opportunities (non-prioritized) we've identified are:

• Lack of a unified golden "getting started" example which naturally accompanies the user from 0 to built & deployed with dagger.
• Guides are hard to find and contain a lot of duplicated information which is hard to keep consistent
• There's no way to know what's new and what's old. This particularly applies to guides in the case they're updated
• There's fairly annoying amount of repeated information across the different languages
• It's hard for users trying to find a specific combination of requirements. i.e: "I want to develop a Go pipeline in Dagger to deploy in ECS"

List of tasks in order to bring us closer to our goal:

• Single-track docs #4291. Create a unified multi-language "getting started" flow which helps the user going from 0 to a deployed app has interactive snippets (maybe not initially)

  • ref: NextJS learn experience.
  • ref: GraphQL learn interactive queries.

• Move all the guides into a centralized "blogpost" like format that can be filtered by tags and ordered by publish date

• Create some sort of recipe-like tutorial customizer that targets users that know more about what they're looking for. i.e: "Go + Github Actions + ECR + Kubernetes"

  • ref: https://octopus.com/docs/guides

• Allow to embed playground snippets

  • ref: https://pkg.go.dev/strings#Compare (embedded example snippets)

WDYT? what are we missing?

[gerhard]

I know that @vikram-dagger has been thinking about this too. There is a related private discussion here: https://github.com/dagger/dagger.io/issues/1190

[marcosnils]

I know that @vikram-dagger has been thinking about this too.

yep, we aligned with Vikram before creating this.

[mircubed]

Yes, I was about to echo what @gerhard mentioned. When Vikram gets back from PTO, he will be focusing on the next version of the docs and creating a proposal for next steps.

I agree with all these issues and improvements. For the guides, we should think about a way to highlight them from the blog homepage and Dagger homepage too.

[crjm]

Centralizing examples in a directory and placing them as snippets in the markdown files will allow examples re-usability across projects + make example testing easier as talked about in the Issue Party.
@dolanor

[mircubed]

@marcosnils do you think we could move this from a discussion to an issue to start tracking a docs 2.0 MVP?

[marcosnils]

@marcosnils do you think we could move this from a discussion to an issue to start tracking a docs 2.0 MVP?

@mircubed sure. I thought we wanted to make a first-pass here to get a 👍 from the team before promoting to issues but if you already brought it to the founders and we're good SGTM!

[shykes]

I am excited about improving our docs of course, but advise against a “docs 2.0” effort. We’ve had endless big bang “2.0” efforts, I know it’s tempting but it is never worth it. The ideas listed here are good, but they should be broken up into a backlog of orthogonal improvements, and rolled out incrementally. Otherwise feature creep and subsequent remorse are guaranteed.

Create a unified multi-language "getting started" flow which helps the user going from 0 to a deployed app has interactive snippets (maybe not not initially)

This is a massive project on its own. We need single-track docs that can be consumed by all Dagger developers regardless of language and SDK. Ideally across all guides, and API reference too.

I strongly recommend focusing on this before expanding the scope too much. Let’s call it something specific, like “single-track docs” or “stripe-style docs”, to avoid scope creep and “accidental docs rewrite syndrome”.

[marcosnils]

We’ve had endless big bang “2.0” efforts, I know it’s tempting but it is never worth it. The ideas listed here are good, but they should be broken up into a backlog of orthogonal improvements, and rolled out incrementally. Otherwise feature creep and subsequent remorse are guaranteed.

I agree with this sentiment. I actually had some difficult to come up with a straightforward title for the initiative and I just put "Dagger 2.0" just to kick it off. You'll also notice that I intentionally present it as an "iteration" to our current docs and not a redesign, we're aligned on the objective here.

I strongly recommend focusing on this before expanding the scope too much. Let’s call it something specific, like “single-track docs” or “stripe-style docs”, to avoid scope creep and “accidental docs rewrite syndrome”.

Agree on this one. Now that we're aligned on the direction, we'll create the issues and start working towards that goal.