Feedback on new Docs Site

[PedramNavid]

Hello Dagster Community!

This is a follow-up to our previous discussion , in which we asked for feedback on our documentation.

First, I wanted to thank everyone who participated. We value your input in helping us understand the shortcomings of our current docs site.

We've since been busy working on a brand new docs site that is much more user-focused, with self-contained examples, more concise pages, and hopefully a better experience for you all. It is full of new features, including:

• Automatic broken link checkers
• API documentation is created during the build process, avoiding ugly merge conflicts
• It is much faster to write and build docs!
• Fully tested code examples
• Built on the Docusaurus platform, giving us access to lots of great features out of the box

Our new docs site will also be easier for you to contribute to; you can click Edit this page at the bottom of any page.

There is still plenty to do, but we wanted to open the new site for all of you to help provide feedback as we complete the migration.

We are already aware of a few issues: not every page is populated, the API docs' styling could be improved, and many concept pages need to be added.

However, we'd love your feedback on the following:

• Overall style and direction of the new documentation
• Whether we have a good balance of breadth and depth in our guides
• Ease of use of our sidebar
• Any other general feedback you may have!

You can find our preview site here: https://docs-preview.dagster.io/

[aleewen]

I approve of dark mode by default 🫡
It's helpful see everything with type-hints so I know what objects I'm dealing with.

[dbrtly]

Not sure if this is solvable but the code snippets are about 3 characters too wide to fit on mobile (iphone 14 pro)

[PedramNavid]

I honestly did not consider people may want to read source code on their phone, but thanks for reporting this, we can definitely get this fixed.

[dbrtly]

For clarity, I don't consider this a bug.
More “oh wow, it almost works on mobile”.
Fwiw I do alot of research reading via phone.

[timoguin]

Quick feedback as I'm looking through things!

These two sections are pretty rough on mobile. (I do read a ton of documentation and code on my phone.)

[PedramNavid]

Thanks for the feedback! We'll definitely try and improve this.

[timoguin]

My apologies for only mentioning the negative (so far)! Just wanted to share before my brain forgot. ☺️

[v1gnesh]

Is this expected?

Also, please document everything about dagster.yaml !

[PedramNavid]

Yep our screenshots are not yet fully done, so we have placeholders. We have a task to document dagster.yaml as a reference guide in the works!

[v1gnesh]

Please add info about deploying the web server with certs (secure), and maybe having nginx/caddy in front.
I'm guessing this is a common pattern...?

[PedramNavid]

This type of documentation is likely out of scope unfortunately. There are many patterns here and it can vary quite a bit from user to user, and having to maintain that type of documentation is really difficult.

[dbrtly]

Fwiw I’ve been using uv to install everything python for several months and I can’t go back. Traditional pip now looks and feels broken.

Also I respect your progress on the docs. They reflect care and attention to detail. Thank you.

[dbrtly]

I found it significantly faster when installing dagster. I saw your other post waving goodbye to pyenv too. No updating pip. How did we like such animals for so long?

Am curious about the Venn diagram of dagster_curious/users to uv_curious/users. Intuitively seems like they would appeal to the same people.

[v1gnesh]

+1 for uv. A little blurb about configuring uv for an env with HTTP proxy & repository (PyPI) proxy will also save time if people are looking to setup uv in corpo envs.

[dbrtly]

+1 for uv. A little blurb about configuring uv for an env with HTTP proxy & repository (PyPI) proxy will also save time if people are looking to setup uv in corpo envs.

Sounds more like a blogpost for you

[v1gnesh]

Why, am I the only one working in a corpo env, and using dagster?
I'm just floating ideas to common paths people will take.
This is an opportunity to save time for your (dagster's) users, and I'm just suggesting it.

[dbrtly]

Fwiw, I am interested in the “how to dagster in corporate” docs you describe. I think there may be significant variations between orgs though.. Example: my org uses GCP so the docs would talk about GCP’s identity-aware proxy (IAP) and artifact registry or direct link to the GCP docs.

[dbrtly]

I've been thinking about migrating the quickstart to uv run

Would you like help?

[PedramNavid]

always accepting PRs. you can find the docs under docs/docs-beta/docs

[dbrtly]

I created issue #24878 .
Dagster needs a little fine tuning creating the pyproject.toml to play nicely with uv.
After that updating the docs to include uv as an option should be clean and simple.